Little fix:
The documentation sources (docbook 5) is available here:
<http://svn.nuxeo.org/nuxeo/doc/nuxeo-book/trunk>.
Eric Barroca wrote:
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
_______________________________________________
ECM mailing list
[email protected]
http://lists.nuxeo.com/mailman/listinfo/ecm
