[Zope3-dev] Documentation: Where do we go from here?

[Anders Schneiderman]

To  kick off a conversation about how we might begin to restructure Zope3 =
documentation, I've written up a quick draft of one way we might go.  =
Sorry for the length; I wanted to get a fair amount out on the table.  I =
promise not to deluge you again!
------------------

Our Goal:  To figure out how to organize the creation and organization of =
documentation so that it satisfies the needs of the people who will use it =
and the people who write it.


The first place to start is to ask, what do we know about how users use =
documentation?  In the literature on usability testing, there seems to be =
a rough consensus on the following:

1)  Most users hate to read documentation and will avoid using it if at =
all possible.

2) If users get so stuck they need to read documentation, they consistently=
 ask for two things:

a) Documentation that's focused on specific tasks they want to accomplish =
or problems they need to solve.  This includes both the content of the doc =
and its organization.
b) Lots and lots of examples. =20

3) Most users don't read documentation;  they skim it.=20


How about the producers of documentation?  IMHO, most of us would agree =
that...

1) Most programmers hate writing documentation.  The more work it is, the =
less likely they'll do it.  Also, the more work it is, the less likely it =
will be updated when the code changes, which means it rapidly goes out of =
date.

2) Many good programmers can't write good documentation.  To write good =
doc, you need to get your head around where the users of that documentation=
, from the most sophisticated to the least.  That's very hard for some =
programmers.  So while they may be an important step in writing the doc, =
they can't be counted on to do the whole thing.

3) All producers of text, such as documentation, have to be edited.  When =
professional writers produce copy, it gets edited by one or more other =
people.  The reason is that it's much, much harder to catch problems in =
your own writing, even if you're a skilled writer.


OK, so what does this all mean?  Here are my suggestions for where we go =
next:

1) For anything involving point-and-click (vs. scripting), we should focus =
more of our energy on usability testing the user interface instead of the =
documentation.

Since most users don't read written documentation, the only "documentation"=
 they're really going to use is the user interface.  And the best way to =
build really good user interfaces is to do lots and lots of usability =
testing.  In some sense, usability testing is to building great UIs what =
unit tests are to writing great code:  everybody is sure their code works, =
but the only way to be _sure_ is to test it.

Usability testing doesn't have to be complicated.  With a few simple =
techniques and a relatively small expenditure of time, we should be able =
to radically improve Zope3 user interfaces.

This doesn't mean that we won't need lots of documentation.  No matter how =
well designed a user interface is, people will always need some help =
navigating it, particularly when they need to do tasks that aren't =
commonly used. And obviously we'll need documentation for scripting.  But =
if the goal of writing documentation is to ensure the system is as easy as =
possible for users, then spending time making an interface easier to use =
will often have a better payoff than writing really good documentation.


2)  Where we need documentation, focus on creating "recipes" with examples =
rather than writing long texts. =20

The Perl Cookbook is a great example of how effective this approach can =
be--not only because its recipes are very useful but because the recipes =
are very well organized.  Obviously there are some exceptions, such as =
when you are laying out the conceptual model behind the system, but what =
users consistently show  researchers is that they learn the most from =
recipes and lots and lots of examples.=20


3) Replace use cases with recipes & examples

When I talked to Jim yesterday, he said one of the ideas he's been kicking =
around is having developers write a draft of documentation--essentially =
writing the equivalent of a quick email you'd send to a friend to explain =
how something works--instead of or largely in place of use cases.  Since =
use cases aren't really used after the unit tests and the code have been =
written, and since we need documentation, why not use doc for laying out =
what a component will do?

I think we could take this idea a little further by replacing use cases =
with recipes and lots of examples.  When use cases first came on the =
scene, many of the people pushing the idea said that a good use case =
should run through how the code would handle a variety of problems or =
options.  Many developers, like Zope3istas, have switched to writing much =
simpler use cases, in part because it's too much damn work for text that =
won't be used at the end of the project.  But if a developer was writing a =
series of recipes that documented how a user can perform a task, you'd end =
up with documentation that would get used _both_ during the writing of the =
code and during later modifications to it. =20

The other thing we might want to consider is to allow (but not require) =
developers to add short FAQ- style explanations of why certain tasks can't =
be performed (e.g., 'What does the error message, "Illegal widget munging" =
mean?').  I don't know whether this is worth doing.


4) Use documentation as an integral part of the functional and usability =
testing of components.

If you want to know, does this component make sense, there's nothing like =
trying to write clean, clear documentation for it.  If nobody can, then =
the component is either too complex or not well thought out or not focused =
enough on the goal, giving users the tools they need to perform particular =
tasks.  And if the documentation for a component is getting too long, it =
may be a sign that a component is trying to do too much and needs to be =
refactored.

It's also a good way to catch naming problems.  For example, as I was =
reading through the Zope3 component tutorial, I was a little confused by =
the security term "protectClass."  From the doc and the example, it seemed =
like you were "protecting" a class by allowing more access, which was =
counterintuitive.  It might be that the documentation wasn't clear =
enough--it's only a draft--or it might be that it makes sense to replace =
"protectClass" with another term, such as "accessClass."


5) Offload some of the work of editing and organizing documentation off of =
developers and onto folks who want to work on documentation.  Frankly, if =
there are developers who want to write a "scratch draft" of their =
documentation, I'd be happy to edit it, and I'm sure we could find other =
people to help as well.  =20

This approach also gives people another reason to offer editing help.  =
Usually when many of us read documentation, if we don't understand what =
the person is saying, we feel stupid.  But when you're editing documentatio=
n, parts that are unclear are a sign of a problem on the part of the =
person who wrote the documentation, not you (it's also a nice way to =
sublimate some of your sadistic impulses that come from any feelings of =
inferiority you may have).


This is my first take on the topic.  Any thoughts?


Thanks,
Anders Schneiderman
Information Manager
SEIU International

P.S.  Anybody have any idea why my postings are=20
showing up w/ =3D20's at the end of each line that
goes beyond a certain length and=20
what I can do about it?  We're forced to use an=20
awful email program here called Groupwise,
so it wouldn't surprise me if it was the culprit.