User documentation for 2.0.0.beta1

[jmesnil]

I've started an outline for the user documentation for 2.0.0.beta1 http://www.jboss.org/community/wiki/JBM20Beta1UserGuideOutline

As for the examples, we could use this wiki page to split the doc task in smaller tasks and do them in parallel.

One thing not clear for me is if we have made a final decision about the documentation source.
Currently we use docbook but Tim talked about using OpenOffice to write the doc. Does that mean the source will still be in docbook or do we keep it in ODF and generate the docbook from it?

I'm non-plussed about using OpenOffice for tech documentation (or any wysiwig editor for that matter) and I don't know how well docbook is supported. The only requirement I have is the ability to create permanent anchors for sections in HTML exportation so that I can link to them from the examples.

[timfox]

For me there are two main criteria:

1) I don't want to be editing XML directly, this just gets in the way of the flow of authoring and makes it a PITA

2) Documents need to be mergeable so multiple people can work on them at the same time without having merge nightmares.

I have never found a good wysiwyg editor for docbook. (I tried and failed to find one).

I suggest we author in, say, open office, and save as either a) pdf b) docbook c) odf which are all xml formats and hence mergeable.

wdyt?

[ataylor]

1) I don't want to be editing XML directly, this just gets in the way of the flow of authoring and makes it a PITA

+1

2) Documents need to be mergeable so multiple people can work on them at the same time without having merge nightmares.

I have never found a good wysiwyg editor for docbook. (I tried and failed to find one).

I suggest we author in, say, open office, and save as either a) pdf b) docbook c) odf which are all xml formats and hence mergeable.

wdyt?

Open office and save in docbook for me!

[jmesnil]

I evaluated Docbook support for OpenOffice and the results are mixed.

* Multiple chapters is not supported. Our doc is split into separate chapters that are included in the master.xml "book".
When I edit one of the individual chapter, OOo does not recognize it as a docbook subset and display the source text (with xml tags)

=> We'd have to aggregate all our document in a single file to be able to use OOo (this means more svn merge operations)

* OpenOffice Docbook support is not complete. If I add a toc tag to the file outside OOo (to generate the table of contents in the output formats), OOo removes it when I save the file.

=> Table of contents would have to be generated from OOo. This means the document generation will no longer be automated

* Section ID. I've some issues to create permalink to sections. Either I have a duplicated title (only 1 having the permalink ID) or none. I'm still figuring out how it works

To sum up, using OOo and saving in docbook:
* does not allow to edit manually the file (changes will be lost next time the file is saved by Ooo)
* prevents automatic generation of HTML/PDF (missing TOC)

I'm not an OOo expert and there may be ways to circumvent these limitations but I haven't found them.

[timfox]

What about ODF and PDF?

[jmesnil]

"timfox" wrote:
What about ODF and PDF?

OpenOffice saves ODF documents in a zip file, so we won't be able to resolve conflicts. Ditto for PDF (it is a binary format)

If we got the OOo way, the best approach would be to save in ODF (that's the best format for OOo), make sure we communicate on document changes to avoid svn conflicts.
And we'd have to generate the HTML and PDF documents manually when doing a release.

Is that ok for everybody?

[clebert.suconic]

In my opinion we should keep whatever you want during the creation phase.. and after it's ready we should convert it to Docbook.

[timfox]

Regarding the structure of the docs, I would like to have

a) Quick start guide
b) User guide

Also, I think we should take a look at the Hibernate documentation. They have really great docs which have proved a great success to them.

I think we should follow their lead and structure our documentation in a similar way.

http://docs.jboss.org/hibernate/stable/core/reference/en/html_single/

[timfox]

I've put together a revised outline on the wiki, which is similar to Jeff's but goes into more depth.

[ataylor]

Theres 4 books, why don't we take one each to start of with.

[timfox]

"ataylor" wrote:
Theres 4 books, why don't we take one each to start of with.

You're welcome to do that if you like, although the user guide is probably going to be 10 times longer than the other guides.

I'm going to start with a few chapters from the main user guide, I've marked my name by them on the wiki. If anyone wants any other chapters from it, then feel free and mark your names by the chapter too.

Again, before starting I recommend everyone reads the Hibernate docs before starting. Some other JBoss projects have good docs too, it's worth having a quick skim.

[jmesnil]

"ataylor" wrote:
Theres 4 books, why don't we take one each to start of with.

I'll bootsrap the quick start guide

[timfox]

For diagrams I am creating a new open office draw file for each chapter which has diagrams and naming it XXX.odg where XXX is the name of the chapter.

This then goes in user-manual/en/diagrams.

I think we should all follow this convention

[jmesnil]

one note on the diagram links: the linkend must point to images/XXX.jpg and not ../images/XXX.jpg to appear correctly in the HTML and PDF we generate.