directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefan Seelmann <seelm...@apache.org>
Subject Re: Documentation -> docbook ?
Date Mon, 09 Aug 2010 15:51:59 GMT
Hi Felix,

first, thanks for starting this discussion.

On Mon, Aug 9, 2010 at 5:13 PM, Felix Knecht <felix@otego.com> 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.

Yes.

> 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?

IMO only manuals. So for ApacheDS the 'Basic Users Guide' and the
'Advanded Users Guide', if we want to keep that separation.

> 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?, ..?)?

For the HTML output I think we should use the current website layout,
for both ApacheDS and Studio. What we should think about if we want to
generate HTML as multi page or single page or both.

For PDF I think plain white looks best, maybe we can add a header and footer.

> 3. When talking only about manuals -> how shall the be integrated into
> the existing website?

Can be done like for Studio. Deploy the generated static files to
p.a.o and add the links to Confluence.

> 4. How can the generate docbook docs be deployed and when shall they be
> deployed?

It would be nice to deploy them automatically during a release. I
think for Studio that is a manual process atm.

Additional it would be nice to generate and deploy snapshots during
the CI build. (Infra, especially Brett Porter set up a new Continuum
instance, btw.)

> 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.

In Studio the user manuals have the same version as the main product,
I'd prefer this.

> There're probably more task to be solved before, so please complete the
> list.
>
> Do other things (e.g. like a favourite docbook editor) also need to be
> discussed?

I played a bit with the XMLmind editor. But I must say I don't feel
comfortable with it. For example I wasn't able to add a new paragraph.
And after I edited a simple link and looked into the sources then the
link appeared twice.

I'm already used to edit XML directly. I have my personal template
list for often used stuff (bullet list, image, table, etc.).

> Do we need to vote in the end of this discussion?

If no one complains we can just reach lazy consensus [2] :-)

Kind Regards,
Stefan


[2] http://www.apache.org/foundation/glossary.html#LazyConsensus.

Mime
View raw message