Date: 2005-01-18T01:42:22
Editor: ReinhardPoetz
Wiki: Cocoon Wiki
Page: CocoonDocumentationSystem
URL: http://wiki.apache.org/cocoon/CocoonDocumentationSystem
no comment
Change Log:
------------------------------------------------------------------------------
@@ -41,6 +41,7 @@
\ /
`---'
}}}
+
The center of the new architecture is SVN. SVN contains all Forrest
repositores. For the first, these are[1]:
* 2.1 docs
@@ -57,10 +58,13 @@
http://cocoon.apache.org/2.2/............... contains the periodically (e.g.
every 6 hours)
published docs
}}}
+
----
+
''Note that publishing multiple versions is good but can lead to confusion
when people search on the web and get a page from a different release than what
they are using. I'd suggest a note/link on each page, clearly stating to which
version of Cocoon this page applies, and giving access to the version
navigation (ideally a link which searches for the same info in other versions,
but that's for a future release ;-)'' - [wiki:BertrandDelacretaz BD]
-''After the discussions on [EMAIL PROTECTED] I dropped the idea of publishing
patch release docs'' ReinhardPoetz
+''After the discussions on [EMAIL PROTECTED] I dropped the idea of publishing
patch release docs. See the new drawing above that already reflects this. If
you're interested in the original version of it, look into one of the former
versions of this wiki page.'' ReinhardPoetz
+
----
The "living docs" docs that are periodically published out of the current
repositories contain an "edit" and a "comment" link. This link is redirected to
a web application where authors can write new docs or comments, e.g.
@@ -69,6 +73,7 @@
http://cocoon.apache.org/comment/2.2/23.html -->
http://someapacheserver.apache.org/webedit/comment/cocoon/2.2/23.html
}}}
+
The web application at http://someapacheserver.apache.org/webedit/ has
following features:
* edit a document e.g. document 2.2/23.html (everybody)
@@ -104,6 +109,7 @@
[1] If 2.2 is coming soon we should concentrate on 2.2 docs
== Document format ==
+
I propose the format that the default configuration of the
HTMLCleaningConvertor generates. What is good enough for Daisy should work as
well for us ;-)
Alternativly we can use plain HTML4. This would have the advantage that the
document can be edited using any HTML editor.
@@ -123,16 +129,18 @@
}}}
Splitting up the docs into three parts has the advantage that the structure of
each document is simpler, editors can be used to edit the content only. Also
Openoffice goes this way.
+
----
+
''The SimpleContentModel idea might also be good, it uses a slightly different
but interesting model, where a documents is either a single xml file or a
directory containing the main document and additional files'' -
[wiki:BertrandDelacretaz BD]
-----
+
''This is what I propose, that does not contain a metadata file. The author
and dates infos are in the source file, while the history is in SVN... no need
to replicate stuff. The comments stuff can be added as a Forrest plugin. Maybe
putting the comments in a doc.comments directory, with each a separate html
file would be nice.'' - [wiki:NicolaKenBarozzi NKB]
{{{
17.html ........................ contains the content
17.comments.xml ............... contains user comments
}}}
-----
+
''For the comments stuff, see my proposal in the Cocoon whiteboard. I simply
added it in a custom pipeline - see
http://svn.apache.org/repos/asf/cocoon/whiteboard/doc-repos/2.2/src/documentation/sitemap.xmap.
About skipping the meta infos, I'm not sure. I also want to provide info about
status, target audience, keywords and this for all languages. Putting this
information into plain text makes it hard/inpossible to explicitly use it in
the publishing process query it in the future. Here the structure of a document
on the filesystem:''
In the repository, each document consists of a directory, which can contain
following files:
@@ -149,7 +157,10 @@
''The changes include the ideas from Bertrand and Nicola. Additionaly I added
a location for mimes (images, attachments like ZIPs) and the option for having
the content in multiple languages available.'' ReinhardPoetz
+----
+
== Document identifiers ==
+
I think we should move away from speaking names like "custom_components" and
use plain numbers and put all documents into a flat directory. Speaking
identifiers are nearly always a problem in data modelling.
Advantages:
@@ -159,20 +170,27 @@
Note to auto-generated docs: Every process that generates docs automatically,
has to use a unique numbering scheme (namespace) so that IDs can't conflict
with existing docs.
+----
+
''Apart from the very controversial idea of having numbers as IDs, the most
important part is the flat structure (WIKI style) of all documents. (see
http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=110593998230556&w=2 by
Stefano). Structuring of content is IMO not a concern of the repository but of
the publishing process. Forrest offers everything we need.'' ReinhardPoetz
''After reading other's opinions I withdraw my proposal, and will use flat
URLs with speaking identifiers.'' ReinhardPoetz
+----
+
== Forrest repositories ==
+
See http://svn.apache.org/repos/asf/cocoon/whiteboard/doc-repos/ for two
examples that work with the latest SVN version of Forrest 0.6.
== Published docs ==
+
The proposal for new global docs and user docs are available at
http://apache.org/~reinhard/cocoon/1.html. Note that the page is generated out
of two forrest repositories.
The global repository is responsible for the tabs "Projekt" and "Community".
The tabs "Getting started" and "Documentation" link to the most recent,
editable userdocs. Older (frozen) docs get their links in the second-level pelt
in the "Documentation" tab.
= What do we have to do? =
== Step by Step ==
+
The good news is that we don't need all the features at once. We can go the
path to better docs and a better documentation system step by step:
* Step1: Setup Forrest Repositories
@@ -200,6 +218,7 @@
* Upayavira will invest a large amount of his time into writing and updating
docs.
= Readers comments =
+
Please use ''italics'' to add comments above this line, or write more
extensive comments and ideas below.
* Tagging documents with simple free-form keywords, as done for links on
[http://del.icio.us/] or pictures on [http://www.flickr.com/] is a very
powerful yet simple way of providing many useful navigation paths in the
documentation. Even if tag-based navigation is not implemented right away, it
would be good to add tags (like "sitemap config FileGenerator Generator 2.1.1"
for example) when revising existing documents, as opposed to having to revisit
all documents later on to tag them. - [wiki:BertrandDelacretaz BD]
