[ZDP] FYI: Documentation Futures

[Amos Latteier]

Tom Deprez wrote:

> 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!

I like this too. I think community members have generated a lot of good
material via How-Tos. On addition to How-To's that I'd like to see is
some kind of peer review process to make it easier for folks to make
comments on a How-To, so that the author knows that someone is reading,
and so that folks who have questions or find problems can easily alert
the author.

> 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.

ZTopics should address this Real Soon Now (tm).
 
> * 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

So the plan is to be able to view all Zope documentation from one
customizable interface?

> * 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.

I can definitely help with doc tools development and with publicizing
the ZDP. Though if I'm going to play a role in development, I'd like
drag things out into a more structured development process--collect
requirements, and usecases, do some modeling, etc.

>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

I agree.

> * What format should the Guides be maintained in?
> 
> grin, have you read all ZDP mails :-).

Is it that clear that I can't keep up ;-)

> 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?),

Info on docbook is available a number of places including
http://docbook.org and http://www.nwalsh.com/docbook/index.html

> 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....)

DocBook is fairly complex, so perhaps it wouldn't be a good choice if
simplicity is the most important factor. The things docbook *does* have
going for it is that it is fairly popular for technical documentation
and it is well supported by free tools.

-Amos