In terms of style, I'm a huge fan of the HBase manual you mentioned at the beginning (which of course borrows style from the FreeBSD manual).
I think documentation of this form would be great - it would seem to meet the needs of some recent users who have been asking for something comprehensive and ordered. I would definitely love to contribute to this effort! On Tue, Dec 10, 2013 at 11:44 PM, Bruno Mahé <[email protected]> wrote: > On 12/10/2013 07:52 PM, Konstantin Boudnik wrote: > >> Super good idea! Would it be beneficial to simply do it on the Confluence >> and >> export in PDF as needed? Just thinking out loud. >> >> Cos >> >> > I thought about it as well but ended up going this way because: > * Generating a PDF from the wiki requires to log into confluence. And this > does not really seem obvious. For instance why can I export to PDF this > unrelated page https://cwiki.apache.org/confluence/display/Hive/DesignDocsbut > cannot see that option for any of our Apache Bigtop pages? > * Generating the doc ourselves gives us greater control over the output > (css, style...) > * It's a personal opinion, but I feel more comfortable with things I can > review and commit > * Another personal opinion, but such document forces me to structure it. A > wiki gives me too much freedom and I usually end up spread all over the > place (which is great in some cases). > * We have had the wiki for years. So let's give it a try to this new way. > If it does not work, we can always retire it. > * The doc becomes naturally versioned and bundled with the source artefact > and our releases. > * It opens up the doors to some crazy ideas related to processing or > generating some reference data. Ex: extracting the users created by a > package from our package content description resources (ie. files like > bigtop-tests/test-artifacts/package/src/main/resources/yum/hadoop-client.xml > ) and integrating this into our documentation as part of the doc build. > > Thanks, > Bruno >
