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

[Paul Everitt]

I'd like to make a metaproposal about what to do next.

We're slowly breaking Zope 3 into smaller, focused projects with clear 
leaders.  Internationalization, cataloging, and workflow come to mind.

This has long begged for a "projects.zope.org" (or zope.org/projects) 
page that lists all the projects, their leaders, description, and links 
to the facilities for the project (mailing list, collector, wiki, 
whatever).  This projects page is inspired by Simon Michel's suggestion 
and mockup from two or three months ago, as well as python.org's sigs page.

The idea of project that I'm mentioning isn't the same as project on 
dev.zope.org, which is a fixed-length endeavor.  This newer idea of 
project is a permanent area of responsibility, so perhaps a different 
piece of jargon should be chosen.

Thus, I propose that we create a zope-docs project that has a charter, 
clear leadership, sets goals, and produces results.  There appear to be 
a number of people that are serious about putting some time into getting 
momentum going.

With Anders getting involved, there's the opportunity to do something 
like a sprint, where we all get in a room in the DC area and actually do 
some things.  Plus with pair programming, Anders' RSI can be avoided. :^)

--Paul

R. David Murray wrote:
> 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
> 
> 
> _______________________________________________
> Zope3-dev mailing list
> Zope3-dev@zope.org
> http://lists.zope.org/mailman/listinfo/zope3-dev