As a member of the ZDP, as well as several other Documentation Projects, I understand exactly where these complaints are coming from. I'm still in the learning stage of Zope, and I admit, am stumbling over the current *official* documentation; nonetheless, I think I'm gaining a foothold. I'm not going to say what Digital Creations should do about this dilemma, but present several options: 1. Create a good communication with the ZDP. As far as I know, not much if any of the ZDP's effort has made it into official documentation. Let's encourage eachother, not point fingers. Let writers know that they are needed; even better, compile a list of EXACTLY what needs to be written/updated. 2. Have volunteers mine the mail archives and compile notes. There is TONS of excellent questions/answers to real world situations on everything Zope. Let's start going through and indexing them. 3. Put together TUTORIALS. If you know how to do something, document it. I'm sure someone would appreciate it. Contact the ZDP, and we'll put up a good collection. 4. Proofread. Many of the Official Guides have typos and broken code examples. Let Pam know. A simple page# description would help ALOT. 5. NEWBIES: Instead of just requesting help on something, request someone to make a How-to. This is another way we can gather priceless material instead of letting it dissolve into the mail archives. 6. A Hypertext help-system integrated into the Zope installation. 7. What tools? Here are some tools we could decide to use for docs (+/-): - DocBook SGML/XML DTD: Powerful, standardized; yet complex - VERY complex. - StarOffice: good Word Processor, supports multi-user docs (redlining, etc.), free; Big, some say bloated. - Structured Text: native to Zope, easy to write in; not functional enough, can't convert to different formats easily - CONGLOMERATE: This could be our answer - an XML-based Document editing/management system, FREE (GPL'd); not yet completed... (www.conglomerate.org) I thing Conglomerate could be our solution. But for now, let's bump heads and work together, and put reality back into check. Eron Lloyd
On Sat, 11 Dec 1999, Eron Lloyd wrote:
- Structured Text: native to Zope, easy to write in; not functional enough, can't convert to different formats easily
Structured text is not a bad idea IMO. It is very easy to write and its simplicity appeals to many people. Of course it lacks features like references indeces etc, but those are easy to add at a later stage. I know of a structured-text to latex module so all the fancier features can be added through latex. It will not be difficult to write a module to convert structured text to any other structured document. Pavlos
Documentation submissions in structured text is very appealing. We are researching ways to convert the structured text to DocBook. Pam Crosby Technical Writer Digital Creations mailto://pam@digicool.com ----- Original Message ----- From: Pavlos Christoforou <pavlos@gaaros.msrc.sunysb.edu> To: Eron Lloyd <woodsage@op.net> Cc: <zdp@zope.org>; <zope-dev@zope.org> Sent: Saturday, December 11, 1999 10:28 PM Subject: Re: [ZDP] Documentation Solution
On Sat, 11 Dec 1999, Eron Lloyd wrote:
- Structured Text: native to Zope, easy to write in; not functional enough, can't convert to different formats easily
Structured text is not a bad idea IMO. It is very easy to write and its simplicity appeals to many people. Of course it lacks features like references indeces etc, but those are easy to add at a later stage. I know of a structured-text to latex module so all the fancier features can be added through latex. It will not be difficult to write a module to convert structured text to any other structured document.
Pavlos
_______________________________________________ ZDP maillist - ZDP@zope.org http://lists.zope.org/mailman/listinfo/zdp
On Sat, 11 Dec 1999, Pam Crosby wrote:
Documentation submissions in structured text is very appealing. We are researching ways to convert the structured text to DocBook.
Nice! I think though that structured text should have some support for simple tables. I have patches if you want them. Pavlos
Date sent: Sat, 11 Dec 1999 22:44:35 -0500 (EST) From: Pavlos Christoforou <pavlos@gaaros.msrc.sunysb.edu> To: Pam Crosby <pam@digicool.com> Copies to: Eron Lloyd <woodsage@op.net>, zdp@zope.org, zope-dev@zope.org Subject: Re: [ZDP] Documentation Solution
On Sat, 11 Dec 1999, Pam Crosby wrote:
Documentation submissions in structured text is very appealing. We are researching ways to convert the structured text to DocBook.
This would be _very_ interesting. Could you be a bit more specific? Can we help in any way?
Nice! I think though that structured text should have some support for simple tables. I have patches if you want them.
Um, I think there are more interested parties for _that_ Pavlos! :-) (here's one at least)! Rik
On Sun, 12 Dec 1999, Rik Hoekstra wrote:
Um, I think there are more interested parties for _that_ Pavlos! :-) (here's one at least)!
Rik
A few more zopistas asked for the code so I have placed it on the zope site: http://www.zope.org/Members/gaaros/StructuredText A few notes ... Last night I realised that StruturedText was modified to make it thread safe. So I just modified and added my patches to the latest version. As such it has not been tested enough. Also new lines are not supported in cells (you can use <BR>), otherwise the plain text version of the structured text doc will look ugly. If anyone has any ideas let me know. Pavlos
Pavlos, i've finally gotten around to incorporating your table code to the distributed StructuredText.py. I haven't spoken with pam and the other docs folks about their requirements, so i'm not sure about the upshot of all this, but your changes definitely look good! Re how to deal with newlines in the table text, i don't see obvious syntax to deal with that implicitly. Since, it seems to me, the fundamental StructuredText philosophy is to place high priority on having the source text look natural and deal with the common cases, and not allow the less common cases force artifical/unintuitive layout in the source text, it seems appropriate to let people needing to do the complicated thing explicitly complicate their source with html markup (eg, <br>)... Ken klm@digicool.com
participants (5)
-
Eron Lloyd -
klm -
Pam Crosby -
Pavlos Christoforou -
Rik Hoekstra