directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Emmanuel Lecharny <elecha...@gmail.com>
Subject Re: Documentation -> docbook ?
Date Mon, 09 Aug 2010 15:47:00 GMT
  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


Mime
View raw message