[Zope] Use the source Luke -- what could be done to help documentation process? Request for comments!

[Heimo Laukkanen]

Chris McDonough wrote:


> (FWIW, as of today, I am at least nominally in charge of documentation =
at
> Zope Corporation.)


Cool!

=20
> At the moment, I am concentrating on improving the state of the canonic=
al
> "booklike" docs (the Developer's Guide and the Zope Book).  Since it's =
a
> part-time job (I'm also doing customer work), it's going to go pretty
> slowly.  But it is going. =20


Well those are the best kick start material available. I confess that=20
before the zope book I was totally out like _____ ( insert your own item=20
according to your preference ).


>   - Make the "canonical" place for the Zope Book a BackTalk book in
>     order to allow easy commentability.  Currently the Zope Book
>     only allows comments via a SourceForge tracker.  The "canonical"
>     version of the Zope Book is currently kept in CVS, which is not
>     readily commentable by the average reader.


This is good.

Also I have a suggestion for a new appendix for the book: case examples.=20
I don't know about others, but real life or mock up examples how to=20
design zope applications is really really good material. Even though=20
there are more than one way to do a thing, it would be good to see=20
examples with and after the canonical material.

So in the next version of the printed book there would be a cd packed=20
with code-examples ,-)

=20
>   - Develop a system for producing "release" documentation
>     at each Zope release.  The release documentation will be immutable
>     and downloadable in PDF and HTML.  For example, there will
>     likely be PDFs and HTML tarballs of the DevGuide and Zope Book
>     made for each Zope release.  The "canonical" version (in BackTalk)
>     will be culled for comments at each release and edited.  Optimally,
>     when a release is made, all the comments will be addressed and
>     removed from the BackTalk version to start afresh.


What is the status of Zope Help-files - and what is going to happen with=20
them?


>  That means that a few motivated
> individuals will need to bear the brunt of reviewing, editing, categori=
zing
> all existing content on Zope.org.  Then a system will need to be built =
(or
> repurposed -- ZDP) that makes the process easier the second time around=
. ;-)
> Then the system needs to be used, which means it needs to be easy.


Yes. I remember some time seen some proposition about rating system for=20
zope.org products. That would be nice, since peers would be able to rate=20
and comment on products. Also the feature to send comments to the maker=20
-- and also on the product page, would be nice. Meaning that if there is=20
a product which looks in words good, but in reality is buggy crap, and=20
the writer is long gone.. for example changed company and email address=20
etc.. users could write comments about their luck with product / howto -=20
etc.


>   - try to find all the best "nuggets" in the form of HowTos and whatno=
t
>     and try to fold these into the Books (ZB and DevGuide) in the form =
of
>     new chapters or paragraphs.


Yes. What is your feeling about including examples of using outside=20
products for Zope in these new chapters. For example I am a small fan of=20
the exUserFolder product for providing authentication against postgresql=20
. I wouldn=E4t mind teaming up with some other people and writing a=20
document about the whole exUserFolder as an example...

exUserFolder is actually pretty nice specially when one uses it with cmf.

=20
>   - kickstart new.zope.org. (zzzz... ;-)  New.zope.org has a lot of the
>     features that we've been wanting like workflow for docs and product=
s,
>     if it ever gets out.


And there is the warning and achtung on the frontpage... veeery=20
reassuring ,-)

 =20
> Well... sure.  If you were to come up with a set of guidelines for
> submitting documentation snipplets, it would be great.  I could then pu=
t it
> up on the docs page.  Getting folks to follow those directions will be =
kinda
> hard, but it'd be a start.
...
> Great!  I'm up for any suggestions.  Whatever we do, it needs to be
> reasonably low-maintenance and fairly simple (and quick) to implement.

Well how about if now for starters we would continue discussion on the=20
mailinglist and then you could open a Zwiki-page somewhere, where we all=20
could start the work on these guidelines.

I emphasise that compared to many writers and readers on this list I am=20
a newbie, eventhough that I've been playing around with zope almost a=20
year soon. But we don't all have to be too seasoned zopistas to help the=20
cause, since I feel that there are many things that could be told more=20
easily than now.

Zope is not that easy, it takes time and commitment -- but sooner or=20
later provides enligthment.

-huima, 5 am here. Time to continue writing my work ,-)