[ZDP] FYI: Documentation Futures

[Tom Deprez]

<snip>

> ZTopics should address this Real Soon Now (tm).

Howdie, another nice Zope product? Wait guys, we've documented the other yet
:-). And other aren't released yet (ZPortal).

<snip>

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

Sort of. We've split up all the sort of documents and came to some
categories. Then we made a basic class and all the others inherit from this
one. The basic class has several properties on which it can be filtered and
thus customization should be easy and possible in a nice way.
Documentation is great, but it needs to be sorted in a way (and preferable
in a nice, easy way). eg The web is great to find information, but sometimes
you need to find very specific and long... People ancious to use software,
need to have there specific docs very quickly, otherwise they turn their
back to you... All has to be easy and familiar, thus most things need to
have all or some of the same capabilities

<snip>

> I can definitely help with doc tools development and with publicizing the
ZDP.

Great! Owesome!! (but you need to know, that I and also suppose other ZDP
active members, aren't that good in programming Python, Zope. That's why ZDP
tool isn't here yet :-()

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

The requirements (once done) can be found here :
http://www.zope.org/Members/srichter
In fact http://zdp.zope.org/FolderTom comes from the requirements.

I agree the proposed tool needs some better modeling (but I don't know how,
never done such processes).
I'm always here to help, do lot's of this work (but I'm a newbie to all of
this)


> * What format should the Guides be maintained in?
<snip>
> 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.

Well, in fact the format depends how we want ZDP-tool to react. For first
entry, I would suggest to use plain text and structured text. Then perhaps,
with the help of the editors (so not necessarely the writers themself:
backing up Dody's proposal!) some information can brought to higher
levels... for instance ZBook can be brought to a real book... Perhaps some
semi-automatic tools can help (in a later stage)

Tom.