On 8/9/10 5:13 PM, Felix Knecht wrote:
If we want to switch documentation to docbook I think it's time to talk
about it, so we can get documentation ready in parallel to the release
of a next release of the application.
It seems I'm not the only one playing around with docbook plugins.
I'm the same opinion like Stefan, that the docbkx plugin [1] can be a
good and quite easy solution to generate html/pdf from docbook.
Going to test this one.
Apart from moving existing documentation and updating it there are some
other task which are IMO to be solved before starting docbook documentation:
1. About which documentation are we talking? Are only the manuals for
the Studio/ApacheDS application meant (I hope so) or do we talk about
the whole website?
ApacheDS documentation, mainly, as Studio Documentation is already in
good shape (except that it has to be migrated to DocBook).
Now, that raises the question : should we have 2 doco, ne for studio,
the other one for the server? IMHO, I think they are quite different.
2. What kind of customization do we want/need? ATM we have a
recognizable layout for all the directory stuff. Shall this layout be
kept for docbook documentation if possible (html?, pdf?, ..?)?
yes, if I understand your question : same presentation as the web site.
But we could be creative too...
3. When talking only about manuals -> how shall the be integrated into
the existing website?
Good question. It would be great if the HTML generated doco was uploaded
on to the web site, as we do with confluence atm. That means we have to
keep a track of many links and keep them updated.
Or we can just provide a pdf, plus a raw HTML downloadable file.
4. How can the generate docbook docs be deployed and when shall they be
deployed?
To be discussed further
5. How dependent are the docs in relation to the applications - are the
docbook docs a separate module or are they included as module in the
related application? IMO the docs should be releasable independent of a
release of he application, otherwise it's difficult to fix documentation
bugs.
Independant.
There're probably more task to be solved before, so please complete the
list.
I think we should first start with a table of content. I started a while
back with XMind to define a raw table of content, I'm wondering if it
would not be a good idea to create a subproject for doco where we store
commons file ?
Do other things (e.g. like a favourite docbook editor) also need to be
discussed?
We should be able to process the code base (doc code base) in the used
tools. So far, I don't know about any other tools able to manipulate
docbook files but OOo, or vi... :/
Do we need to vote in the end of this discussion?
No. Vote are for situations where we don't have a consensus. I'm not
sure we are in this phase :)
--
Regards,
Cordialement,
Emmanuel Lécharny
www.iktek.com
