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

[R. David Murray]

I'm willing to put in some time on docs/editing.  I'm a fair dinkum
technical writer, though I've never managed to sustain an extended
writing project <wry grin>.

On Wed, 13 Mar 2002, Anders Schneiderman wrote:
> 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.

There is another class of documentation, though, and that is the
technical reference.  The tech ref is not designed to be *read*
cover to cover, but rather to facilitate the as-needed look up of
individual *authoritative* and *complete* element descriptions,
and thus doesn't fall under the constraints above.  In Z3 this
would be a combination of various artifacts that should be
produced as part of the code development process, primarily the
Interface specifications.

So the documentation project needs a way to gather that information
into a technical reference.  That should be pretty easy to automate,
and may even simply consist of pointers into the codebase.  In
theory the process of code development and use should see to it
that the reference docs get made complete and accurate, but in
practice there might be a role for the documentation group in that
as well.  Certainly the editing aspect would be *very* useful, and
may even catch some design/code bugs <grin>.

Presumably one would also like a "guide to the technical reference"
that would outline how things fit together.  Some of this material
is what already exists in the Wikis, and I think encompases (or
is) the "laying out of the conceptual model" that you refer to as
an exception to your task-oriented documentation model.

> 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.

Sounds good to me.  I don't think I've ever found an example of
documentation of a GUI that was worth reading; they mostly tend to
consist of screen shots, which almost always differ at least subtly
from the actual (current) user interface.

On the other hand, the "task oriented" documentation (to get the
following task accomplished you are going to need to access the
following management screens and do the following actions, and
here's why) will, as you say, be necessary.  (But please no
screenshots and no "click on xxx and select yyy" type stuff; that
had better be obvious when you look at the UI).

> 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.

I have used something similar to this style in several projects of
my own, and not only does it produce as useful end product
documentation, it can also help clarify the design process.
Not just by twigging you to the fact that the component is
too complex or too large, as you say, but also in the subtle
details.  I find that when you explain how to do something,
and you find yourself saying something like, "but in case X
you can't do Y, you have to do Z", you often find out that
your design can be simplified.  In several cases when I got
to that point I realized that I had taken a "shortcut" in the
design, but found when it came time to document that shortcut,
I couldn't stand to admit that I'd done it and instead was
motivated to go back and "do it right" <grin>.

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

I think this is an excellent idea.  In XP one is supposed to write
unit tests before writing code, and certainly we don't want things
getting checked in without unit tests.  I wonder if it would be
too much to also require at least a minimal set of "task docs"
before checkin?  Assuming these are indeed taking the place of the
use cases?

(NB: I have a feeling using task docs instead of simple use cases
would help bring design controversies to closure faster.)

Thanks for taking on this coordination task!

--RDM