[ZDP] ZDP Tool update
Maik Roeder
roeder@berg.net
Thu, 23 Dec 1999 18:16:02 +0100
Hi !
There are some new ideas for the ZDP Toole project, which I have found
on the Zope homepage of Stefan Richter.
http://www.zope.org/Members/srichter
Perhaps this can stir up the discussion a little bit.
Greetings,
Maik Röder
Version 0.8 23 Dec 1999
News:
1. I have got a member page mock-up page done. I will set it up
on the ZDP homepage soon.
2. I had a look at the "old" Requirements Document by Stefan Richter.
I will write about some parts of it in the Discussion section.
Not all can be covered now and here. I look back at it later.
http://www.zope.org:18200/Members/srichter/requirements/index_html
Links:
1. The ZDP project Requirements Document by Stefan Richter.
http://www.zope.org:18200/Members/srichter/requirements/index_html
I will write about some parts of it in the Discussion section.
Not all can be covered now and here. I look back at it later.
2. ZDP Process, which Stefan Richter proposed for the ZDP project.
http://www.zope.org:18200/Members/srichter/process/index_html
I will have a close look at it later.
3. ZDP Active Members
http://www.zope.org:18200/Members/srichter/members/index_html
Changes:
1. Made the role Maintainer an explicit role. Before that, it
was just a property of a DocumentFolder
Discussion
1. Flexibility in Design
Martijn Faassen noted that "The initial quick deployment design
should anticipate the possibility of extension later on. At least
the data formats should allow for such extension (note: XML
allows fairly easy conversion).
In the current Design, the question of a data format is not an
issue. There is just a DocumentFolder container, which can hold
whatever data the member cares to throw in. My Design is more
about how people work together on the project, and what services
can be offered. The format question can be answered once we have
a first running version of the ZDP tools.
2. Categories
Stefan Richter noted that a standard set of categories should be
set. These categories may not be extensible in version 1.0, but
should be flexible enough to be dynamic. The categories also
should be the same for the FAQ and the Reference Manual.
This could enable us to cross-link the two documentations.
3. Area Editors (Tasks and Process)
Rik Hoekstra pointed out that the effort should be focussed.
This may be done by dividing responsibilities by "assigning"
different parts of the documentation efforts to specific
volunteers. This way work loads are divided and we can concentrate
on specific parts of the task. Also, keep everyone concerned
updated about the progress of the various tasks.
We have a Role of a Maintainer, who has a certain project under
his auspices. The progress can be seen from activity reports
local to the DocumentFolder. Up to now, we have not thought
about Tasks for a project. I'll add this to the Ideas section.
4. Beginner, Advanved and Expert level documentation
Rik Hoekstra said that Documentation is used in many different
ways and the level of users of specific parts of the documentation
is not always obvious or the same. For example: someone who is
very experienced in one area may be a beginner in another, or
explaining some advanced features often requires starting at the
basis.
I'll add this to the Idea section.
5. Documentation reusal
Rik Hoekstra said, that documentation organization should be
such that different sections can be reused in other parts of the
documents. Fulltext searching is not enough here. A clever
(if simple) keyword system combined with ZCatalog may help. This
will be hard to accomplish with XML. XML could be the output format
though.
How about a box like "Related documentation" by keyword ?
6. Example Code
Rik Hoekstra suggested to include (annotated) example code with
all features documented. Show it on the documentation site itself
make it available for download.
How about a box like "Related Snippets" by keyword ?
7. Editor Role
Stephan Richter explained that the solution should allow the
average user (Actor: AnyUser) to add questions to the FAQ and he
should also be able to answer questions. For quality reasons I
would strongly suggest an editor (Actor: Editor) who can edit
and proof-read the questions and answers before they get publish.
The editor should be trusted and is not responsible for the
technical content. The community itself will correct mistakes
over time.
This would mean that AnyUser can not put a NeedsReader ZClass
into these sections. An Editor has to do this.
8. Submission Date and Product/Version data
Brian Hopper stressed that we need to include submission date
and product/version data with FAQ items, since some FAQs may be
relevant only for a particular version of Zope, or a particular
Product. This would also facilitate the removal of old / outdated
information (an inaccurate FAQ may be worse than no FAQ at all!)
9. Categories
Brian Hopper brought up the discussion about what categories are
appropriate for the FAQ ? Here are the different classifications
that Brian suggests to produce different views on the same FAQ
data:
1. FAQ entries which are oriented toward audiences of varying
technical expertise (DTML developers, Python programmers,
content managers, designers/users) could then be organized that
way.
2. Another obvious one might be by what Product/feature the
question is about (Confera / ZCatalog / ZClasses)
3. What activity someone is trying to do (for example, connect
Zope to this or that RDB).
Ideas
1. Rik Hoekstra suggested
1. introducing tasks for project parts and progress reports for
the tasks.
2. introducing documentation levels from beginner to expert
documentation.
3. reusal of parts of the docomentation. Perhaps this can be done
with a box like "Related documentation" by keyword ?
4. annotated example code with all features documented. Perhaps
a section like "Related Snippets" by keyword could do ?