directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Kiran Ayyagari <kayyag...@apache.org>
Subject Re: Documentation -> docbook ?
Date Mon, 09 Aug 2010 18:10:03 GMT
hi Felix,

On Mon, Aug 9, 2010 at 9:21 PM, Stefan Seelmann <seelmann@apache.org> wrote:
> Hi Felix,
>
> first, thanks for starting this discussion.
yeap, thank you Felix for bringing out this dormant idea
>
> 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.
IMO, think it is better to have this distinction, at least for some more time
>
>> 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.)
+1
>
>> 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.
yeap, this is the better way to tag the product and its doc
>
>> There're probably more task to be solved before, so please complete the
>> list.
I think we need to first export all the existing documentation(present
in the confluence)
to docbook, so we really get an idea about where to start from and
another advantage is
we have a place to immediately make the changes and push to SVN rather
than procrastinate
due to the hassle involved in logging into confluence then writing
within all those wiki macros
>>
>> 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.
>

Kiran Ayyagari

Mime
View raw message