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/DesignDocs but 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
