[Zope3-dev] Zope 3 documentation

[Gary Poster]

From: "Paul Everitt" <paul@zope.com>
> This projects page is inspired by Simon Michel's suggestion
> and mockup from two or three months ago, as well as python.org's sigs
page.

Paul, is this mockup still on the web somewhere?  Do you have a link?  I'm
not familiar with it.

(Addressing how to keep people interested in doc writing)
From: "Anders Schneiderman" <SCHNEIDA@seiu.org>
<snip>
>First, one way to help with this problem is to set it
>up so that much of the documentation can be written
>or edited in increments & still be useful.
<snip>

Yes.  And another is to set it up so that the docs can be organized
incrementally.  A wiki can accomodate both of these needs...which brings me
to more wiki thoughts, and more thoughts on Paul's proposal of a long-term
"charter" for a docs project.

(Before I proceed, let me reaffirm that yes, I am willing to be one of the
folks who actually work on implementation of these ideas.  The ideas just,
um, need a bit of pruning and shaping.)

Three observations.

First, wikis are good.  They encourage incremental editing, allow
incremental organization, have versioning and now emailed change alerts.
They are ideal for "living" documentation.  Moreover, the vast bulk of the
current Zope 3 docs are in a wiki, and changing that would be inefficient.

Second, wikis aren't perfect.  They only allow structured text, do not
encourage clear structural organization (particularly as is needed for a
printed doc), have only one workflow and set of permissions, and use a link
formatting convention ("camel case") that is inappropriate for normal
documentation.  Not encouraging clear structural organization also leads to
occasional duplication of effort within large wikis: arguably (if not
necessarily accurately), the Zope 3 glossary and cheat sheets are an example
of somewhat duplicated effort that bolsters my point.

Lastly, *huge duplication of effort* is a problem in the whole Zope doc
world.  Within ZC projects alone we have the built-in help system; the Zope
documentation project; filesystem docs like INSTALLs and READMEs and other
text files in the actual Zope distribution; and wikis.  Add to that little
pages of personal notes held in Zope Member pages and sites like the Zope
Cookbook, and you have a content management nightmare.   Filesystem docs are
not necessarily up to date, while the needed new information might be on a
wiki somewhere; the documentation project might have a gaping hole for a
given topic while the help system says all you need to know.  Or all sources
discuss a topic, covering similar ground, and effort is wasted.  Or, as is
often the case, a little-known member page holds the only key to the realm.

So: wikis are good, wikis aren't perfect, and Zope docs are not managed
efficiently.

A fantastic goal to brainstorm on, I think, would be to see if Paul's
proposal could lead to a long-term solution that consolidated at least some
of the disparate doc efforts, using, in my conception, a kind of super-wiki
product.

Specifically, this solution might include some or all of the following
features.  Please note that I am aware that many of these are far from
trivial tasks, and may be impractically difficult--I am brainstorming,
hoping to further the discussion.

 - *primarily*, a way to link documents from the wiki/library into actual
Zope distributions, both as part of a help system and as part of README,
INSTALL, and other filesystem docs.  In this way, there is one central
document store, and changing a document in the central doc tree also updates
the help system, the filesystem docs, and any other projects of which the
doc is a part.  *All* documents are available from one hopefully logically
organized tree TTW.

 - *secondarily*, a way to categorize pages and then extract pages from the
doc tree so that only a given type of docs is included. In this way,
super-wiki pages could be tagged for inclusion in a resource for newbies, a
resource for developers, a resource for content managers, or whatever.

 - a way to add many types of non-structured text docs into the tree (as in
the Kaivo Document Library)

 - a way to convert camel case links into normal-looking text (for
structured text, I would suggest giving the option to replace the camel case
link with the linked page's title, for instance)

 - a way to add product and help docs within the large tree of docs so
product coders and other community members can contribute their thoughts to
a more organized whole.

 - workflow and permissions for pages and branches within the tree

Thinking of implementation, of course, brings me to wanting ye olde
ObjectHub relational plug-in already, because this kind of functionality
really would be ideally implemented as something that could take advantage
of normal Zope folder structure and functionality but that could also
address each document in a "flat" space...

Good tree organization is also necessary, but as far as I know that's purely
in the realm of the human noggin: occasional wiki-tree pruning and
straightening will certainly be required by some folks who are presumably
charged with that task.

OK, I've spent too much time thinking about this today: somebody else join
in, if they care to. :-)

Again from: "Anders Schneiderman" <SCHNEIDA@seiu.org>
>Second, since you've put out where you're coming
>from, let me put out my interests:
<snip>

It seems to me that both of our perspectives might lead to some bite-sized
motivational blurbs for a project front page somewhere... Anyone else?

Gary