Date: 2005-01-17T01:19:34
Editor: NicolaKenBarozzi
Wiki: Cocoon Wiki
Page: CocoonDocumentationSystem
URL: http://wiki.apache.org/cocoon/CocoonDocumentationSystem
no comment
Change Log:
------------------------------------------------------------------------------
@@ -2,7 +2,7 @@
* make writing docs as simple as possible
* separation between global docs (docs about the project) and user docs
* evaluate the existing docs (no automatic doc import into new repositories)
- * enable comments for docs
+ * enable comments for doc
* have a modular architecture (having a repository and webspace should me
enough to run, other features should be "plugable")
I don't think that a technical solution will directly lead to better docs. I
just think that making the doc authoring process easier will invite much more
people to help out.
@@ -92,12 +92,22 @@
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.
+''I propose HTML as a base format. Forrest is able to render it without
problems, and the Incubator website uses it as a source format.'' -
[wiki:NicolaKenBarozzi NKB]
+
In the repository, each document contains of 3 files:
{{{
17.xml ........................ contains the content
17.meta.xml ................... contains meta information (date, authors,
history)
17.comments.xml ............... contains user comments
}}}
+
+''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.'' -
[wiki:NicolaKenBarozzi NKB]
+
+{{{
+ 17.html ........................ contains the content
+ 17.comments.xml ............... contains user comments
+}}}
+
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]
