[ZDP] FYI: Documentation Futures

[Alexandre Ratti]

Hi Anthony,


Sounds interesting.

- We can post information about drafts on the zope and zdp mailing lists, 
but postings have a short life time. However, they go to many readers.
- We can use a Web-based system. Postings stay up longer but readers have 
to go to them.
=> I think this is an important issue because we need to attract the 
attention of experienced users on the howtos and docs. We need their feedback.

How about:
- A Web-based system for posting, discussing and updating howtos, as you 
suggested? Should be fairly prominent.
- When drafts are added or updated or versions are released, emails could 
be sent automatically on the main zope and zdp lists to inform readers. 
Simple version management definitively sounds necessary.

To avoid unnecessary traffic, I guess the Web system could compile a change 
log for the day and send a daily update about docs. This log could include 
a short description (entered when submitted) and a link to the text.
For instance:

...
Newly added howtos

- Setting your cat on fire with DTML (submitted by Jean Dupont)
Version 0.1 - 1999/10/28
Category: DTML hacks
Description: This doc explains bla bla bla
Read it:<http://site/dir/dir/doc/>
Comment it: <http://site/dir/doc/comments/>

Updated howtos
- How to avoid the computer-melt down bug (updated by XXX)
Version 0.2 - 1999/10/28
Category: ...
Description: ...
Changes: ...
Read it:<http://site/dir/dir/doc/>
Comment it: <http://site/dir/doc/comments/>

etc.

Maybe a weekly update log could also be send to the announce list. The 
issue here is keeping in touch with the lists because they are a major 
information channel.

I need to look closer at the proposals mentioned by Tom Deprez.


Cheers.

Alexandre


At 20:38 27/10/1999 +1000, Anthony Baxter wrote:
> >>> Alexandre Ratti wrote
> > I'll second Amos here. We'd need a peer review process for howtos so that
> > new users who want to write one can feel more confident about there 
> writings.
> >
> > Writing a howto is very useful both for the writer and other users, but 
> you
> > don't want your misconceptions to end up in the final docs.
>
>What about some sort of slashdot-like discussion attached to howtos?
>
>You'd then look at some sort of moderation or rating system, then maybe
>an auto-revision of howtos (including version numbers?)
>
>The discussions would attach to a particular revision of a howto - so the
>author could take the comments, and fold them into a new version.
>
>Seem reasonable?
>
>Anthony
>--
>Anthony Baxter     <anthony@interlink.com.au>
>It's never too late to have a happy childhood.