Chris McDonough wrote:
(FWIW, as of today, I am at least nominally in charge of documentation at Zope Corporation.)
Cool!
At the moment, I am concentrating on improving the state of the canonical "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.
Well those are the best kick start material available. I confess that before the zope book I was totally out like _____ ( insert your own item 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. I don't know about others, but real life or mock up examples how to design zope applications is really really good material. Even though there are more than one way to do a thing, it would be good to see examples with and after the canonical material. So in the next version of the printed book there would be a cd packed with code-examples ,-)
- 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 them?
That means that a few motivated individuals will need to bear the brunt of reviewing, editing, categorizing 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 zope.org products. That would be nice, since peers would be able to rate and comment on products. Also the feature to send comments to the maker -- and also on the product page, would be nice. Meaning that if there is a product which looks in words good, but in reality is buggy crap, and the writer is long gone.. for example changed company and email address etc.. users could write comments about their luck with product / howto - etc.
- try to find all the best "nuggets" in the form of HowTos and whatnot 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 products for Zope in these new chapters. For example I am a small fan of the exUserFolder product for providing authentication against postgresql . I wouldnät mind teaming up with some other people and writing a document about the whole exUserFolder as an example... exUserFolder is actually pretty nice specially when one uses it with cmf.
- kickstart new.zope.org. (zzzz... ;-) New.zope.org has a lot of the features that we've been wanting like workflow for docs and products, if it ever gets out.
And there is the warning and achtung on the frontpage... veeery reassuring ,-)
Well... sure. If you were to come up with a set of guidelines for submitting documentation snipplets, it would be great. I could then put 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 mailinglist and then you could open a Zwiki-page somewhere, where we all could start the work on these guidelines. I emphasise that compared to many writers and readers on this list I am a newbie, eventhough that I've been playing around with zope almost a year soon. But we don't all have to be too seasoned zopistas to help the cause, since I feel that there are many things that could be told more easily than now. Zope is not that easy, it takes time and commitment -- but sooner or later provides enligthment. -huima, 5 am here. Time to continue writing my work ,-)