Hi,
We are progressing on the reference documentation for Nuxeo EP (yes,
I know, it's a great news! :-).
You can see the current state here: <http://doc.nuxeo.org/1.0-
SNAPSHOT/reference>. It's published automatically by hudson after
each commit into the doc.
The documentation sources (docbook 5) is available here: <http://
svn.nuxeo.org/doc/nuxeo-book/trunk>.
I have made some refactoring on the documentation layout to prepare
for a more componentized and reusable content (thanks to docbook 5
and xinclude). To goal is to create atomic content units assembled
into larger pieces to create a modular documentation corpus that can
be used as needed to produce various documents.
Here is how it works:
- at the root, we found documentation assemblies (ex: nuxeo-book,
developer-guide, etc.) that assemble content into specialized guides.
- each important part (let's call it a module) has its own
subdirectory which contains content files, pictures, and attached files.
- For each module, we have an index.xml which will reference
module's content units. It's important, in the future, to create
separate files (starting with the <section> tag) for each content
unit of the module (ex: in administration, we will have admin-
datasources.xml, admin-extensionpoints.xml, admin-backup.xml, etc.).
Each content unit will be reference in the module's chapter but will
also be available for direct inclusion into specialized documents/
guides. This part of the refactoring still need to be done, but the
infrastructure is here. Starting from now, please create a new file
for each important part of a module documentation you start (and use
a unique xml:id for the root section).
- Set an xml:id to any section that might be reused into another
document (even if it's not the root section of the xml document).
XInclude/XPointer allows to reuse part of an xml document into
another one.
- when you need to include large piece of code, please use
XInclude to do so. It keep the docbook clean and ease the maintenance
of those code samples. See here for an example: <http://svn.nuxeo.org/
trac/nuxeo/browser/doc/nuxeo-book/trunk/src/docbook/administration/
index.xml?rev=19587> (line 102).
As a background, you can read "Modular Docbook" from "DocBook XSL:
The Complete Guide": <http://www.sagehill.net/docbookxsl/
ModularDoc.html>. It's very interesting.
Any help from the community would be very welcome to improve the
quality of the documentation. It's not very difficult and helps a lot
(especially for typos, tests, feedback on part, etc.)! :-)
The documentation system is still at the beginning but we will work
on it as much as we can to provide a high-quality and usable
documentation.
Thanks,
EB.
--
Éric Barroca - Ex. VP of Operations - +33 6 21 74 77 64
www.nuxeo.com - Nuxeo: Open Source ECM - www.nuxeo.org
Nuxeo EP 5: extensible, Java EE and standards based ECM Platform !
_______________________________________________
ECM mailing list
[email protected]
http://lists.nuxeo.com/mailman/listinfo/ecm
