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

[Anders Schneiderman]

Ooo, sign me up!

Thanks,
Anders

>>> Paul Everitt <paul@zope.com> 03/13/02 03:46PM >>>

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

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

This has long begged for a "projects.zope.org" (or zope.org/projects)=20
page that lists all the projects, their leaders, description, and links=20
to the facilities for the project (mailing list, collector, wiki,=20
whatever).  This projects page is inspired by Simon Michel's suggestion=20
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=20
dev.zope.org, which is a fixed-length endeavor.  This newer idea of=20
project is a permanent area of responsibility, so perhaps a different=20
piece of jargon should be chosen.

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

momentum going.

With Anders getting involved, there's the opportunity to do something=20
like a sprint, where we all get in a room in the DC area and actually =
do=20
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>.
>=20
> On Wed, 13 Mar 2002, Anders Schneiderman wrote:
>=20
>>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
>=20
> 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.
>=20
> 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>.
>=20
> 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.
>=20
>=20
>>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.
>=20
>=20
> 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.
>=20
> 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).
>=20
>=20
>>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
>=20
> 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>.
>=20
>=20
>>4) Use documentation as an integral part of the functional and
>>usability testing of components.
>=20
>=20
> 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?
>=20
> (NB: I have a feeling using task docs instead of simple use cases
> would help bring design controversies to closure faster.)
>=20
> Thanks for taking on this coordination task!
>=20
> --RDM
>=20
>=20
> _______________________________________________
> Zope3-dev mailing list
> Zope3-dev@zope.org=20
> http://lists.zope.org/mailman/listinfo/zope3-dev=20