[ZDP] FYI: Documentation Futures

Mon, 25 Oct 1999 21:34:54 +0200

Hello!

Wow, nice to hear this!! (my opinion)

* Does this seem like a good general direction?

I think so. What I liked about the new Zope site was that people actually
wrote HowTo's! What I didn't liked was that they are scattered around and
not putten together... Yes, you can search with the keyword 'HowTo' and you
get all howto's, but then you get all of them. Not sorted by category,
platform, etc....  A nice place where all the information is shown and
updated would be great.

* How do/don't the ZBook and ZQR projects fit into this project?

Mmmm, I'm not that familiar with ZQR, so I can't really talk about this.
ZBook can fit into this project. A few months back, we've proposed our new
look of ZDP. We've made some specs on how the ZDP-tool should look like. You
can see them at: http://zdp.zope.org/FolderTom
(Questions? Just ask!!) I think with this proposed way of working, all
information will be updated and everybody can work, also this system is
already a sort of CVS! Of course, this system needs some sort of
maintainers... but everything needs this! Benefit is that EVERYBODY can
actually see if a certain thread is active.
This implies that you still have different categories, like : ZBook,
HowTo's, Tutorials, Reference Manual etc... but this is ABSOLUTELY needed...
not everybody wants the same way of reading information... some like books,
other like short introductions etc...
I think that the DC guides are just another category.... or can be place in
a ZBooks category.... then ZBook will be something for beginners, experts,
...

* What more/else can DC do to empower the ZDP?

Well, we're trying to organise ourselfs. Unfortunately, we're just a very
small team... 2 editors, 2 writers, 1 coördinator and at the moment
ex-writer, 1 designer. At the moment we're thinking of moving to ZDP account
on Zope.org. This until we're with lots of more people, have some thing to
show, our ZDP-tool is made and ZDP changed to Zope2.
At the ZDP account we would make a nice page with some nice graphics (1
person working on it : savvas) and make our ZBookStatus page
(http://zdp.zope.org/ZBookStatus) which is now on the ZDP and very
rudimentary. Why? >>> One place where people can find up-to-date
information. Then we would announce it so that people could watch an
attractive page and hopefully join us....
So what to do to help us more? With one thing your already helping us great!
ie. you're believing in us!!! Perhaps, you could already make an
announcement that you want to help ZDP and that you're standing behind us.
(I think not much people know about ZDP :-(, or forgot about it.
BUT, in what you certainly could help us, is creating the ZDP-tool... if
possible.... I don't know if it's much work, but it would certainly for us,
because we (at least I) don't know how to begin on creating the tool we
proposed at ZDP http://zdp.zope.org/FolderTom. I don't know what you think
about this tool, but I think it will be a very usefull one!!! (I kinda took
the layout from www.experts-exchange.com, before it turned ugly and also
thinking on the php manual (where people can give comments). Perhaps it is
not that much work for you guru's in zope and python to create something
that looks like (or is) our ZDP-tool. If it was, it would certainly be a
good tutorial for all Zope users.

So my BIG dream is that the ZDP-tool will someday be operative and will get
a lot of visitors... (shall I keep dreaming :-)? yes, I know, you don't have
the time either)

However, I only think that ZDP will get much visitors only and only if it is
nice for the eye and easy... (I think the ZDP-tool) would help a lot getting
this attention... Nice and easy, because people like to find information in
a very easy way... ZDP-tool would do... (I think :-) )

* What format should the Guides be maintained in?

grin, have you read all ZDP mails :-). Well, that's the problem isn't it...
We thought on doing it just in plain text, structured text.... From their
other formats should be generated...... Yes, with plain text you can't give
much feeling into the text... But, look at the 2 parts of ZBook now (html!
not structured text at the moment), it's made with Zope's technique... you
can get some nice look...
 I don't know much about Doctool (don't know anything about it, where can I
find it?), but whatever format should be used, it should be very easy to
use.... (even structured text can sometimes be used as the factor why people
didn't gave a comment! Because with structured text you need to know certain
rules....)

Thus this all makes sense? If not, let me know and I'll try to explain it in
another way...

Tom.

----- Original Message -----
From: Amos Latteier <Amos@digicool.com>
To: <zdp@zope.org>
Cc: Pam Crosby <pam@digicool.com>; Rob Page <rob.page@digicool.com>
Sent: Monday, October 25, 1999 8:30 PM
Subject: [ZDP] FYI: Documentation Futures

> Hi Folks,
>
> I'm writing to let you know some of the things we're considering at DC
> in terms of future documentation directions.
>
> It is clear that DC is so far unable to keep up with the documentation
> needs of the Zope community all by ourselves. The ZDP is a prime example
> of how the Zope community has stepped up to address its own needs.
>
> At DC, we're impressed by the ZDP and are considering opening some or
> all of our current documentation (Zope Guides) up to the ZDP.
>
> We believe that this could result in:
>
>   * Better quality documentation
>   * More up to date documentation
>   * More important presence of ZDP in Zope Community
>
> We're imagining a scenario in which documentation is managed in CVS by
> documentation champions. Perhaps docs would be owned on a chapter by
> chapter basis, with community members owning chapters they cared about
> and DC owning chapters that no one wants. DC could supply the initial
> material, and the tools necessary to convert docs to various formats and
> package them up for distribution and to work with a forthcoming on-line
> help system.
>
> Our general questions are:
>
>   * Does this seem like a good general direction?
>   * How do/don't the ZBook and ZQR projects fit into this project?
>   * What more/else can DC do to empower the ZDP?
>
> Our religious ;-) question is:
>
>   * What format should the Guides be maintained in?
>
> Right now we maintain the Guides in Framemaker, but probably this format
> won't work well for the community since it is not free. Our initial
> evaluation suggestions that DocBook is the most likely candidate since
> it seems to be technically adequate and popular. Whatever format is
> chosen, DC would be responsible for the initial conversion of the
> existing Guides to this format.
>
> Please let us know what you think. Your opinions count!
>
> Thanks!
>
> -Amos
>
> --
> Amos Latteier         mailto:amos@digicool.com
> Digital Creations     http://www.digicool.com
>
> _______________________________________________
> ZDP maillist  -  ZDP@zope.org
> http://www.zope.org/mailman/listinfo/zdp
>
>