[ZWeb] Documentation Index

[Rik Hoekstra]

> Andrew Sawyers wrote:
> > I may not be the person in the know on this, but since I have been
working
> > on these pages alot, I am going to comment.  Since we have been
attempting
> > to narrow the focus of the documentation index, so specific
documentation is
> > easier to find.  The organization has been the key.  If we think of it
as a
> > library, books are shelved based on their focus; and the reference
section
> > would contain items which cover a large range of topics, such as an
> > encyclopedia.  I would propose we place items which have a broader
> > relationship to the documentation categories either in reference or we
look
> > at redoing the left nav bar, utilizing it to possibly be a place for
> > important documents which transcend the categorical nature of the
> > documentation index's layout.  At present, that left navbar isn't very
> > useful since the documents listed there are easily found on the new
> > documentation index.  Our goal should be towards making the
documentation
> > easy to find.  I see the table top as being the categorical
structure.....
> > comments?
>
> To me Itamar's document seems more like the library catalog than one of
> the books.  If it had been available when I started learning Zope, I
> would have used it instead of whatever documentation index there might
> be on zope.org.
>
> The only future concern is maintenance.  If we give it a prominent place
> in the documentation, we need to figure out how it will be updated.
>
> However, I'm just making suggestions.  Feel free to implement it how you
> like.


Talking as one of the people who was involved with a Zope community effort
of re-ordering the documents, I may perhaps add some comments. It is not
completely clear to me where the overview page of the documentation stands,
but that is basically a DC thing. Now I don't want to prove I'm right, but I
think there is a basic problem with the categories in the Documentation main
page (while being an improvement over a previous version).
I have said in discussions before (ask Ethan whom I've been pestering with
this for some time ;-)), the division into categories is trying to cram
three different categories into two classifications:

types of users (administrators)
level of documentation (new users vs component developers)
topics (online api reference under reference; help system under new users)

this is bound to lead to problems you cannot solve as they cross categories
(see the problems sketched in the mails). In our classification of the
how-to's (se their management screens under properties) we have made this
three-fold classification.
topics: for example - tutorials, DTML,
level: easy, intermediate, difficult. The level is always concerning the
topic, never in general, as someone may be an expert in one topic, but a
relative newby in another.
audience (basically users vs developers): users of Zope (no matter their
level of expertise) need different docs from developers

The only way to solve the confusion is to separate categories, perhaps by
using the left navigation frame as Andrew suggests. Perhaps this could help
somewhat in the discussion.

my 2 (euro) cents

Rik

P.S. btw, as a result of the reorganization process I put a guide similar in
intent to that of Itamar (but for users) at
http://www.zope.org/Documentation/Overview/Use Comments highly appreciated.