-----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 <[email protected]> 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 <[email protected]> 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-----
