The Documentation chat with Michel and Amos went well, with lots of detailed answers to hard questions. There is also a full log of the chat availiable.

Only the moderated portion of the chat is covered in this summary.

RikH: Amos, how are we going to integrate the tutorial with a quickstart?

Amos: The quickstart as it is needs to go. We need to replace it with more up to date examples. I think the examples in the tutorial would be a good choice. However, we may need a little tweeking on the tutorial infrastructure to make this work well.

For example, everytime you want to use the tutorial, you need to get a fresh batch of examples, so just including the tutorial examples as default content is not sufficient. So in summary i don't have the answer, but I definitely see a lot of overlap between the tutorial and quickstart.

Michel: The quickstart itself is just a good launch point, really we need to take better advantage of that, it's prime real-estate.

ChrisW: Could Amos briefly outline what is to replace the otudated ZCMG, ZDG and ZAG?

Michel: I'll take this one... What we want to do is merge the official Zope docs, the Guides, with the Zope book being published by O'Reilly. None of this is official, BTW, we haven't worked all the kinks out of it. The goals of the guides and the goals of the book line up very well. When you take our revised outline that came out of the recent training material and put it next to the book outline they match up really well. We think it would be a waste of effort for me to write the book and then for amos and I to write the guides when they are largely the same content.

We're pretty excited about this, and we hope that it works out but we haven't yet heard back from O'Reilly, so stay tuned.

RikH & Aquarius: any thoughts about the integration of Zope documentation (in one place?) / how do we combine all this content into a manageable beast?

Amos: This is a difficult question. In general I'm happy to let the ZDP take the lead on this ;-) I would like to see all zope documentation in one place too. In general, ZDP seems like the right place to me. I would like to work more closely with ZDP folks to make sure that if they want this to happen that we give them all the support they need to make it work.

Maik: How are people going to be able to contribute to [ Digital Creation's -m] documentation, and how is the credit going to be given ?

Amos: Again, this is a great question. Everything that will ship with the online help system (help screen content, tutorial, api docs, refs) will be in CVS in an easy to edit format--so we can accept patches. We can also build more complex front-ends to these simple facilities - a la cvsweb As for the guides replacement, that isn't worked out yet because we still don't know if we'll be able to use the O'Reilly Book or not. In any event, the plan is to make all official docs available in CVS in an open format so that folks can contribute to the official docs in the same way they contribute to the source code. As for crediting folks, we currently have a Zope credits, but I don't think that is sufficient for docs credit. If folks contribute to official docs, their names should probably be attached to the actual pages they contribute to. I don't have the mechanics for this worked out yet, and am definitely open to suggestions.

Dracvl As a newbie I would like to propose that there should be a How-to on every submitted product - included with the product. Step-by-step instructions are better than API docs for beginners, and one of the things I remember from my early days was frustration over how many of the products lacked proper How-tos. Thoughts? How about making it kind of compulsory, � la javadocs?

Michel there's a few issues here... The new online help system is a big help here- The system allows you to provide screen by screen context sensitve help, so this removes much of the need for seperate docs with products. The help system also has a facility for providing API docs for your objects, sort of like interface defintions, although that's not the hard and fast rule. Step by step instructions is more like a tutorial format, and how third party products can extend the existing tutorial is not defined, althouh we happily accept contributions to the tutorial about core Zope concepts. The compulsory aspect is a hard issue, we don't want to make anyone do anything. ;)

We certainly encourage it, and we can also set a good example, which we try and do in 2.2 by providing good help on all the standard screens. Keep in mind that some of this work is being done by a fellow ZDPer Stephan Richter

faassen & Aquarius what's the status on using (simplified) DocBook? (where is it used in the documentation currently?) Also, any thoughts on the DocBookDocument product in this respect?

Amos Frankly, I'm having second thoughts about DocBook. It's a complex format. Initially we proposed a two step system whereby you edit docs in XML and then render the results into HTML and then check the HTML into CVS. This has proved cumbersome, folks want to walk up the the docs they need to change, change them and then check them back into CVS

So for simple docs we're now favoring structured-text - its easy to edit and is well supported by the online help system. For more complex docs such as the guides replacement the format is still an open issue and I would not rule out docbook at this point.

Finally, your [faassen's -m] XMLWidgets stuff is very cool, especially in conjunction to the DocBook stuff. It could end up being a very good solution for online editing of textured content.

Right now I'm tring to focus our limited energies on creating quality content in the simpliest way possible For this reason I am hesitent to devote a lot of resources to trying to create complex doc formats and tools.

Michel Also docbook is totally unaproachable by many people and there are few free tools that grok it. It's distracting to look at all those tags... We strongly want to encourage other people to write docs, especially those of us at DC. Really the simplest way to do this is structured text: you will never catch Jim, for example, writing directly in XML. ;)

mindlace Aquarius also suggests that we look at http://www.conglomerate.org regarding a structured doc format.

ChrisW As a maintainer of python products, hwo am I supposed to find out how things like __ac_permissions__ and otehr voodoo work? where will this be documented?

Michel The long range answer is that this will be defined in the API docs that come with the help system. The short range answer is a bit more complex, currently the secuirty API (which __ac_permissions__ belongs to) is in the process of being documented on the interfaces wiki.

The source is also helpful.

Programmer docs are very important, but a higher priority for us at this point is user level docs. The training slides we released today have some good information on where the whole outline of docs is going.

RikH If there is (ever) gonna be a [ZDP] ZBook, would we have to cover any documentation that you (=DC) will not? Are there any plans for what DC documentaition is going to cover?

Amos Later this week we should make public a wiki that describes all our doc efforts and what we are going to cover - refs, tutorial, revamped guides. I agree that it's very important for DC to describe our responsibities so that folks know what docs to expect from us and what they should feel empowered to strike out on, on their own.

So briefly I see DC's priorities firstly as providing the tutorial, and the references - API docs, and DTML refs, etc. Between these two poles is a vast area that the new Guides will partially cover, but there is a lot of room for community docs, especially example oriented docs.

aquarius Now, we all know that the mailing lists is one of the largest goldmines of collective knowledge of Zope. Do you think it would be possible for us to come up with a process of "mining" the mail-lists to extract all this gold?

Michel searchable mail list! yeehaa...this isn't too hard, it just takes time for us to do it, in fact, it's not really high on our list because we are mandated to create new content. This can be done probably rather easily with ZCAtalog and some procmail scripts, in fact, this would be an excellent project for the ZDP or some other community group to do. hmm.. yes, searchability is important, it would be nice and very ego-centric of me for example to be able to search for all the message that I wrote about ZCAtalog (gads there must be thousands...)

tconnect Searchable mail lists at zope.nipltd.com is a grand effort - does about 90% of what I need

mindlace If I may take of the moderator hat for a second I would say that allowing zope-*@ messages to filter into zope.org is high on my personal priority list