Date: 2005-01-14T00:27:47
Editor: BertrandDelacretaz
Wiki: Cocoon Wiki
Page: CocoonDocumentationSystem
URL: http://wiki.apache.org/cocoon/CocoonDocumentationSystem
Added two comments and corrected a typo
Change Log:
------------------------------------------------------------------------------
@@ -63,6 +63,8 @@
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]
+
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.
{{{
http://cocoon.apache.org/edit/2.2/23.html -->
http://someapacheserver.apache.org/webedit/edit/cocoon/2.2/23.html
@@ -98,6 +100,8 @@
}}}
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]
+
== 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.
@@ -107,7 +111,7 @@
* several navigations can be provided
* during the life of a document, a speaking identifier may become out of date
-Note to auto-generated docs: Every process that generates docs automatically,
has to use a numbering scheme (namespace) so that IDs can't conflict with
existing docs.
+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.
== Forrest repositories ==
See http://svn.apache.org/repos/asf/cocoon/whiteboard/newdocs for two examples
that work with the latest SVN version of Forrest 0.6.
