[Zope3-dev] Z3 documentation

[Garrett Smith]

Thanks Stephan,

Would it be desirable to have documentation in a format that is akin to
MSDN, which is bookish but is still usable as a reference? I think
having a solid top-down structure (i.e. a good table of contents) and
carefully defined help topics is an excellent way to manage non-trivial
documentation projects.

There are a few goals that I think are important:

 - Ease of use - readers should not have to be terribly clever or
patient to find answers to questions.

 - Sensible progression - the docs should have a good starting point and
move through topics as a reader might expect.

 - Quality transparency - readers should know the quality level of a
help topic without having to read it. This might be similar to the
Wiki's status badges, but would likely cover things like percent
complete, readability, comprehensiveness, etc.

- KISS - capture relevant documentation as it exists and fill in missing
topics, but avoid getting bogged down with things that no one needs.

Some questions:

1. Is a Wiki still the most suitable format, at this point, for help?
What about docbook? Another format? I would be reticent to use anything
that could not be managed under SCM tools.

2. What is the primary target audience? E.g. Zope2 users? Zope2
developers? General readers outside the Zope community? While well
designed docs can certainly address the needs of multiple groups, it's
generally helpful to identify a primary target.

3. How much bandwidth is available in the development community for
fielding questions about existing help and filling in pieces? I can do
my best to piece together what's available from various Wikis, readmes,
mail archives, etc. but I (others?) will undoubtedly have questions
along the way.

Garrett Smith
Mojave Corporation


> -----Original Message-----
> From: Stephan Richter [mailto:stephan.richter@tufts.edu]
> Sent: Monday, March 31, 2003 8:39 PM
> To: Garrett Smith; zope3-dev (E-mail)
> Cc: sathya
> Subject: Re: [Zope3-dev] Z3 documentation
>=20
>=20
> Hi Garrett,
>=20
> as Sathya metioned, I try to keep the documentation group focused and=20
> oriented. The main page used for the organization of the=20
> tasks and available=20
> documentation is=20
> http://dev.zope.org/Wikis/DevSite/Projects/ComponentArchitectu
> re/Documentation
>=20
> On Monday 31 March 2003 11:56, Garrett Smith wrote:
> > I've got some time over the next few months to contribute to the Z3
> > effort. Having looked over the technology, there's not much I can
> > contribute to in the way of coding -- too new to Python and Z3.
>=20
> Cool!
>=20
> > However, I might be able to help in the area of documentation. I've
> > managed development efforts involving some commercial ISVs=20
> and have a
> > pretty good idea what's involved in delivering high quality docs,
> > particularly for frameworks and tools.
>=20
> Also cool. :-)
>=20
> > Having read through the mailing list archives, I've made a few
> > observations:
> >
> >  - Z3 appears to be congealing (typical for alpha stage) and that's
> > usually a great time to get docs going.
>=20
> I agree.
>=20
> >  - The list is starting to see frequent requests for better=20
> docs from
> > the new and curious. The temptation is strong to respond=20
> with "write 'em
> > yourself, y' whiner" -- but it helps if they have a=20
> process/project to
> > plug into.
>=20
> Right; we try very hard to emphasize documentation from the beginning.
>=20
> >  - There was talk of Z3 docs back here:
> >=20
> http://mail.zope.org/pipermail/zope3-dev/2002-November/003357.
> html - but
> > I haven't seen much activity on it
>=20
> Well, there has been. A lot of the activity is logged in the=20
> Zope 3 CVS and on=20
> the Wiki mentioned above.
>=20
> > My company has decided to use Z3 as the platform for some business
> > applications we're developing, so we have a strong interest=20
> in seeing Z3
> > succeed. My involvement, to whatever extent is needed, will=20
> make that
> > more of a vested interest.
>=20
> Nice.
>=20
> > 1. Is now a good time for a more focused effort on "docs" for Z3? I
> > realize the answer depends on a definition of what "docs" means --
> > leaving this intentionally flexible. Thoughts?
>=20
> Yes; on the Wiki page mentioned above, I tried to outline all the=20
> documentation-related tasks.
>=20
> > 2. Is there a project handling this already that I've overlooked?
>=20
> Yes, the Documentation sub-project that is organized via the Wiki.
>=20
> > 3. Is this the right protocol for volunteering? Do I need=20
> to fill in an
> > application somewhere -- talk to any recruiters? ;-)
>=20
> Certainly. If you want to write docs that make it into CVS,=20
> you can either=20
> give it to anyone with checkin rights or sign up for CVS=20
> access. For the=20
> Wikis you just need a Zope.org username.
>=20
> > Btw, I recognize that there's a lot of documentation for Z3=20
> (have read
> > it), most of which is quite good. It's rare to see such a=20
> disciplined
> > approach for any project, much less an OSS project. But by "docs", I
> > don't mean project artifacts or API documentation. I'm talking about
> > end-user docs -- i.e. developer guides, references, (more)=20
> tutorials,
> > etc. that can be easily accessed.
>=20
> Right, I think at this point we should drive to get the=20
> Cookbook up-to-date=20
> and write new recipes for it. I think there we will spend our=20
> time most=20
> wisely and people can learn about specific problem domains=20
> quickly using the=20
> cookbook. Of course, you can sign up for any other task too=20
> and/or add new=20
> tasks.
>=20
> Regards,
> Stephan
> --=20
> Stephan Richter
> CBU Physics & Chemistry (B.S.) / Tufts Physics (Ph.D. student)
> Web2k - Web Software Design, Development and Training
>=20