You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@directory.apache.org by Felix Knecht <fe...@otego.com> on 2010/08/09 17:13:42 UTC
Documentation -> docbook ?
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.
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?
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?, ..?)?
3. When talking only about manuals -> how shall the be integrated into
the existing website?
4. How can the generate docbook docs be deployed and when shall they be
deployed?
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.
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?
Do we need to vote in the end of this discussion?
WDYT?
Regards
Felix
PS:
It seemed to me that - after various notes on the dev/user list - it's
time to start this discussion. If it's the wrong time, please insist.
Re: Documentation -> docbook !
Posted by Emmanuel Lecharny <el...@gmail.com>.
On 8/16/10 3:33 PM, Pierre-Arnaud Marcelot wrote:
> On 16 août 2010, at 15:28, Felix Knecht wrote:
>> -----BEGIN PGP SIGNED MESSAGE-----
>> Hash: SHA1
>>
>> On 08/16/10 15:16, Pierre-Arnaud Marcelot wrote:
>>> Hi Felix,
>>>
>>> This is already looking very good. :)
>>>
>>> Did you use any script to get and format the content from the wiki to the DocBook format?
>> Nope :-(
>> I found some time and it's handmade (C&P) - a poor mans migration ....
> Ouch... Ouch... Ouch... :'(
>
> Then, you deserve even more kudos for this migration.
Kudos, kudos... How does it translate in english ? Beers ?
Thanks a lot Felix, great job !
--
Regards,
Cordialement,
Emmanuel Lécharny
www.iktek.com
Re: Documentation -> docbook !
Posted by Pierre-Arnaud Marcelot <pa...@marcelot.net>.
On 16 août 2010, at 15:28, Felix Knecht wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> On 08/16/10 15:16, Pierre-Arnaud Marcelot wrote:
>> Hi Felix,
>>
>> This is already looking very good. :)
>>
>> Did you use any script to get and format the content from the wiki to the DocBook format?
>
> Nope :-(
> I found some time and it's handmade (C&P) - a poor mans migration ....
Ouch... Ouch... Ouch... :'(
Then, you deserve even more kudos for this migration.
Pierre-Arnaud
Re: Documentation -> docbook !
Posted by Felix Knecht <fe...@apache.org>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
On 08/16/10 15:16, Pierre-Arnaud Marcelot wrote:
> Hi Felix,
>
> This is already looking very good. :)
>
> Did you use any script to get and format the content from the wiki to the DocBook format?
Nope :-(
I found some time and it's handmade (C&P) - a poor mans migration ....
>
> Thanks,
> Pierre-Arnaud
>
> On 16 août 2010, at 13:57, Felix Knecht wrote:
>
> I finally finished taking over the guides from the wiki. It wasn't
> always easy to guess the chapter and section sequences, anyway ...
>
> Here's the first result:
> Basic User Guide html:
> http://people.apache.org/~felixk/basic-user-guide/html/book.html
> Basic User Guide pdf:
> http://people.apache.org/~felixk/basic-user-guide/pdf/book.pdf
>
> Advanced User Guide html:
> http://people.apache.org/~felixk/advanced-user-guide/html/book.html
> Advanced User Guide pdf:
> http://people.apache.org/~felixk/advanced-user-guide/pdf/book.pdf
>
> Hope, this is the way we can continue, even if not all docbook tags are
> fully correctly used.
>
> Regards
> Felix
>
> BTW:
> Hope there weren't too many changes in these documentations in the last
> days you guys have done and I didn't catched ...
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.16 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
iEYEARECAAYFAkxpPOsACgkQ2lZVCB08qHGcvgCgnFU9nLiSohRO8msYU5MudFh4
u4QAoKRijrk0AEJe3KLwo+oELVG3KZib
=/f1t
-----END PGP SIGNATURE-----
Re: Documentation -> docbook !
Posted by Pierre-Arnaud Marcelot <pa...@marcelot.net>.
Hi Felix,
This is already looking very good. :)
Did you use any script to get and format the content from the wiki to the DocBook format?
Thanks,
Pierre-Arnaud
On 16 août 2010, at 13:57, Felix Knecht wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> I finally finished taking over the guides from the wiki. It wasn't
> always easy to guess the chapter and section sequences, anyway ...
>
> Here's the first result:
> Basic User Guide html:
> http://people.apache.org/~felixk/basic-user-guide/html/book.html
> Basic User Guide pdf:
> http://people.apache.org/~felixk/basic-user-guide/pdf/book.pdf
>
> Advanced User Guide html:
> http://people.apache.org/~felixk/advanced-user-guide/html/book.html
> Advanced User Guide pdf:
> http://people.apache.org/~felixk/advanced-user-guide/pdf/book.pdf
>
> Hope, this is the way we can continue, even if not all docbook tags are
> fully correctly used.
>
> Regards
> Felix
>
> BTW:
> Hope there weren't too many changes in these documentations in the last
> days you guys have done and I didn't catched ...
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v2.0.16 (GNU/Linux)
> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
>
> iEYEARECAAYFAkxpJ8YACgkQ2lZVCB08qHGbgQCdEQ/VHhpIBE/vmtBqaIRHaJdg
> +hUAoIQ5WIaERWCePWOTiLizEx2996e8
> =fkHM
> -----END PGP SIGNATURE-----
Re: Documentation -> docbook !
Posted by Kiran Ayyagari <ka...@apache.org>.
On Mon, Aug 16, 2010 at 5:27 PM, Felix Knecht <fe...@apache.org> wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> I finally finished taking over the guides from the wiki. It wasn't
> always easy to guess the chapter and section sequences, anyway ...
np, now we have a common ground to work on and improve this book,
this is a great effort thanks Felix
>
> Here's the first result:
> Basic User Guide html:
> http://people.apache.org/~felixk/basic-user-guide/html/book.html
> Basic User Guide pdf:
> http://people.apache.org/~felixk/basic-user-guide/pdf/book.pdf
>
> Advanced User Guide html:
> http://people.apache.org/~felixk/advanced-user-guide/html/book.html
> Advanced User Guide pdf:
> http://people.apache.org/~felixk/advanced-user-guide/pdf/book.pdf
>
> Hope, this is the way we can continue, even if not all docbook tags are
> fully correctly used.
>
> Regards
> Felix
>
> BTW:
> Hope there weren't too many changes in these documentations in the last
> days you guys have done and I didn't catched ...
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v2.0.16 (GNU/Linux)
> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
>
> iEYEARECAAYFAkxpJ8YACgkQ2lZVCB08qHGbgQCdEQ/VHhpIBE/vmtBqaIRHaJdg
> +hUAoIQ5WIaERWCePWOTiLizEx2996e8
> =fkHM
> -----END PGP SIGNATURE-----
>
Kiran Ayyagari
Re: Documentation -> docbook !
Posted by Felix Knecht <fe...@apache.org>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
I finally finished taking over the guides from the wiki. It wasn't
always easy to guess the chapter and section sequences, anyway ...
Here's the first result:
Basic User Guide html:
http://people.apache.org/~felixk/basic-user-guide/html/book.html
Basic User Guide pdf:
http://people.apache.org/~felixk/basic-user-guide/pdf/book.pdf
Advanced User Guide html:
http://people.apache.org/~felixk/advanced-user-guide/html/book.html
Advanced User Guide pdf:
http://people.apache.org/~felixk/advanced-user-guide/pdf/book.pdf
Hope, this is the way we can continue, even if not all docbook tags are
fully correctly used.
Regards
Felix
BTW:
Hope there weren't too many changes in these documentations in the last
days you guys have done and I didn't catched ...
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.16 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
iEYEARECAAYFAkxpJ8YACgkQ2lZVCB08qHGbgQCdEQ/VHhpIBE/vmtBqaIRHaJdg
+hUAoIQ5WIaERWCePWOTiLizEx2996e8
=fkHM
-----END PGP SIGNATURE-----
Re: Documentation -> docbook ?
Posted by Emmanuel Lecharny <el...@gmail.com>.
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
Re: Documentation -> docbook ?
Posted by Felix Knecht <fe...@otego.com>.
On 09.08.2010 17:13, 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.
>
> 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?
>
> 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?, ..?)?
>
> 3. When talking only about manuals -> how shall the be integrated into
> the existing website?
>
> 4. How can the generate docbook docs be deployed and when shall they be
> deployed?
>
> 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.
>
>
> 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?
>
> Do we need to vote in the end of this discussion?
>
>
> WDYT?
>
> Regards
> Felix
>
> PS:
> It seemed to me that - after various notes on the dev/user list - it's
> time to start this discussion. If it's the wrong time, please insist.
>
[1] http://code.google.com/p/docbkx-tools/
Re: Documentation -> docbook ?
Posted by Emmanuel Lecharny <el...@gmail.com>.
On 8/12/10 4:23 PM, Felix Knecht wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> On 08/11/10 22:24, Alex Karasulu wrote:
>> This might be a bit off topic yet tangentially related but do any of you
>> guys know of a good WYSIWIG docbook editor that really, I mean really, works
>> right? IIRC, at some point docbook support was added to open office but it
>> had some quirks. Anyone know if that improved as well?
> Just saw this [1], but I haven't tested it yet (anyway I can't say much
> as I'm not a docbook guru ...). Exists for Windows/Linux/MacOSX
> [1] http://www.syntext.com/products/serna-free/
Will test it.
--
Regards,
Cordialement,
Emmanuel Lécharny
www.iktek.com
Re: Documentation -> docbook ?
Posted by Felix Knecht <fe...@apache.org>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
On 08/11/10 22:24, Alex Karasulu wrote:
> This might be a bit off topic yet tangentially related but do any of you
> guys know of a good WYSIWIG docbook editor that really, I mean really, works
> right? IIRC, at some point docbook support was added to open office but it
> had some quirks. Anyone know if that improved as well?
Just saw this [1], but I haven't tested it yet (anyway I can't say much
as I'm not a docbook guru ...). Exists for Windows/Linux/MacOSX
[1] http://www.syntext.com/products/serna-free/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.16 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
iEYEARECAAYFAkxkA9wACgkQ2lZVCB08qHEadQCbBidnzzqo19mGAgxuYj+KTyNr
aK4AniDnyTkTG9MvbOx8Gk/GuDdDujv4
=zglA
-----END PGP SIGNATURE-----
Re: Documentation -> docbook ?
Posted by Alex Karasulu <ak...@apache.org>.
This might be a bit off topic yet tangentially related but do any of you
guys know of a good WYSIWIG docbook editor that really, I mean really, works
right? IIRC, at some point docbook support was added to open office but it
had some quirks. Anyone know if that improved as well?
--
Alex Karasulu
My Blog :: http://www.jroller.com/akarasulu/
Apache Directory Server :: http://directory.apache.org
Apache MINA :: http://mina.apache.org
To set up a meeting with me: http://tungle.me/AlexKarasulu
Re: Documentation -> docbook ?
Posted by Emmanuel Lecharny <el...@gmail.com>.
On 8/11/10 4:09 PM, Felix Knecht wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> I opened an issue [3], trying to summarize and split up into sub task.
Yup, saw the JIRAes :)
Thanks for dealing with this !
--
Regards,
Cordialement,
Emmanuel Lécharny
www.iktek.com
Re: Documentation -> docbook ?
Posted by Felix Knecht <fe...@apache.org>.
-----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 <se...@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 <fe...@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-----
Re: Documentation -> docbook ?
Posted by Kiran Ayyagari <ka...@apache.org>.
hi Felix,
On Mon, Aug 9, 2010 at 9:21 PM, Stefan Seelmann <se...@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 <fe...@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
Re: Documentation -> docbook ?
Posted by Stefan Seelmann <se...@apache.org>.
Hi Felix,
first, thanks for starting this discussion.
On Mon, Aug 9, 2010 at 5:13 PM, Felix Knecht <fe...@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.