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

[Chris McDonough]

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

I'm not sure if you've seen it, but the newest Zopes ship with an=20
Examples folder that contains some simple example applications.  They're=20
not "real world" apps because they're very simple, but they should get=20
folks "up and going".  Maybe there needs to be a Zope Book chapter that=20
explains the examples in the Examples folder.

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

They continue to be updated every release.  The help system=20
implementation might change, but the content will stay the same (or=20
hopefully be improved).  Currently the API reference in the Zope Book is=20
generated right from the help files, but it may make sense to make a=20
different book (API reference or something) out of it to give it more=20
exposure.

> 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 rat=
e=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 i=
s=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.

Yes, parts of this exist in new.zope.org.  I'm not sure that helps a=20
lot, though. ;-)

> 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 o=
f=20
> the exUserFolder product for providing authentication against postgresq=
l=20
> . I wouldn=E4t mind teaming up with some other people and writing a=20
> document about the whole exUserFolder as an example...

I think it'd be a pretty big promise for us (Zope Corp) to make a=20
committment to keep chapters devoted to non-Zope-core products=20
up-to-date, so it'd be a little tough to consider putting them in the=20
Zope Book and DevGuide.

But I think whole "mini-books" could be devoted to topics like=20
exUserFolder and LocalFS.  I'm not sure what form these should be in,=20
but I'm sort of partial to BackTalk for booklike content, and I believe=20
that it's possible for "normal" members to create BackTalk Books on=20
Zope.org, so folks can certainly make use of that if they want to create=20
booklike content.  Then again, a HowTo is fine as well.  It would just=20
be another document that we needed to review when we did a brute-force=20
review of documentation available on Zope.org. ;-)  Our=20
community-contributed documentation management system needs to be=20
simplified and normalized but I know that I can't bite that task off at=20
the moment while I'm concentrating on getting the "official" docs in=20
order.  I'm guardedly hopeful somebody will kickstart new.zope.org in=20
the meantime, which might solve a few of the associated problems for us.

> 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 al=
l=20
> could start the work on these guidelines.

OK, I took you up on that and I've revived the Documentation Wiki at=20
http://www.zope.org/Wikis/Docs.  You need to be logged in to edit.  Note=20
that there is already a *lot* of guideline documentation at=20
http://www.zope.org/DocProjects/ (some of which may be outdated), so you=20
should probably look at that before reinventing anything.

Thanks a lot!

--=20
Chris McDonough                    Zope Corporation
http://www.zope.org             http://www.zope.com
"Killing hundreds of birds with thousands of stones"