directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Felix Knecht <fel...@apache.org>
Subject Re: Documentation -> docbook ?
Date Wed, 11 Aug 2010 14:09:03 GMT
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

I opened an issue [3], trying to summarize and split up into sub task.

[3] https://issues.apache.org/jira/browse/DIRSERVER-1535

On 08/09/10 20:10, Kiran Ayyagari wrote:
> 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
> 

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.16 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAkxirv8ACgkQ2lZVCB08qHGneACeLxrXCXzF4kWCnOhIVSk1ueTV
h/AAn024jiQkAztDgzMyqaska0XRforK
=xp+z
-----END PGP SIGNATURE-----

Mime
View raw message