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

[Anders Schneiderman]

> "R. David Murray" <bitz@bitdance.com> 03/13/02 03:31PM >>>

>There is another class of documentation, though, and that is the
>technical reference.  The tech ref is not designed to be *read*...

Good point; we'll certainly want that doc--although if we can=20
figure out a way to put examples in it, that'd be great...

>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
>is well.  Certainly the editing aspect would be *very* useful, and
>may even catch some design/code bugs <grin>.

Yes, this is exactly where I'd like to go.  This is where Paul's idea=20
comes in--to start figuring out the how's & why's of automating
as much of the documentation generation from places where
it's as easy for developers to write it, _and_ a process that
lets us clean it up.  For editing, I'm not sure how to do
it w/o creating major risks.  Ideally the edits would occur
at the source, so everything stays synched up.  But
how you do that so you wouldn't freak out developers
& would protect against accidentally screwing up someone's
code isn't clear to me. =20

Maybe one way would be to treat the edits like submissions=20
that a developer could accept or reject via a tool--essentially=20
using the Z3 workflow tool (which if you were fixing the doc
for the workflow tool would be truly MontyPythonesque).


Thanks for your thoughts!  I'm glad you're intersted
and I think this should be a fun ride.

Thanks,
Anders=20