+1 for the format of HBase manual, that's definitely good example to start with
-Mikhail 2013/12/11 Sean Mackrory <[email protected]> > 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 > > > -- Thanks, Michael Antonov
