I wanted to revitalize this thread as Bruno's proposed overhaul makes a lot of sense. And it seems that everyone is agreed on this. I had a number of the offline discussions with Sean, Jay, Roman and other guys (not singling out these guys, but otherwise the list would be too long;)
I think we all are in agree that the high level scope does totally make sense and all these guides are very important fr the success of the project. What I want to discuss is the tools that we can use for it. As I see, a requirement to be able to generate a PDF book to hand it out to a user is very important. I want to put upt to the discussion a list of choices that we have to do the job. Once we are in consensus on the toolset/format we can move forward real fast. The way I see it is that the following formats can be used: - docbookx (what HBase uses, XML base format) - markdown (a text based format without much overhead formatting) - asciidoc (similar to markdown, but somewhat different, I don't know much about it) - an online CMS system of some kind I would like to see what you guys think about all this and what would be a preferred way of generating/controlling/managing the versions of the documentation. Please chime in! Thanks, Cos On Sun, Dec 08, 2013 at 09:35PM, Bruno MahИ wrote: > Hi, > > As you are all probably aware, documentation is not our forte. > In order to help with that, I have been thinking about introducing books > similar to the Apache HBase reference guide. > But given how wide is Apache Bigtop, having a single reference guide > would not make sense. So I have come up with 3 books: > * User guide - hand hold users into installing and configuring an Apache > Bigtop installation. Including packages directly, puppet recipes and all > the system (users, locations, ec2...) and tooling around such > installation (firewall, monitoring, logging...) > * Developer guide - All the inner details about contributing packages, > tests and customizing VMs and Apache Bigtop (build my own stack) > * Cookbook - Step by step instructions to reach a given goal (run hive > queries with an hbase backend, logstash...) > > For now I will solely focus on the first one. I have prepared > BIGTOP-1157 to build an HTML and PDF version of the user guide as part > of our website. > It is for now empty but here is a proposal for its content: > > * Preface > > * Introduction [What is Apache Bigtop and why should I care] > > * What is new in Apache Bigtop [features highlights] > ** What is new in Apache Bigtop 0.9.0 > ** Upgrading from Apache Bigtop 0.8.0 to Apache Bigtop 0.9.0 > ** What is new in Apache Bigtop 0.8.0 > ** Upgrading from Apache Bigtop 0.7.0 to Apache Bigtop 0.8.0 > > * What is an application and the need for packages [an application > neeeds users, files, configuration, permissions, ulimits, ports...] > > * Lifecycle of applications > ** Lifecycle of an application [init scripts, logs] > ** Lifecycle of a distributed application [coordination, zookeeper...] > > * GNU/Linux distributions supported by Apache Bigtop > ** centos[presentation, what makes it distinct, how to to main tasks > (install, upgrade, remove packages, restart services, tweak firewall, > where are logs...), setup bigtop repositories] > ** Fedora [presentation, what makes it distinct, how to to main tasks > (install, upgrade, remove packages, restart services, tweak firewall, > where are logs...), setup bigtop repositories] > ** OpenSUSE [presentation, what makes it distinct, how to to main > tasks (install, upgrade, remove packages, restart services, tweak > firewall, where are logs...), setup bigtop repositories] > ** Debian [presentation, what makes it distinct, how to to main tasks > (install, upgrade, remove packages, restart services, tweak firewall, > where are logs...), setup bigtop repositories] > ** Ubuntu [presentation, what makes it distinct, how to to main tasks > (install, upgrade, remove packages, restart services, tweak firewall, > where are logs...), setup bigtop repositories] > > > for project in [Hadoop, HBase, Zookeeper, Flume...]: > * Apache <project> > ** Introduction > ** Installation > ** Configuration > ** Pseudo distribution > ** Distributed > ** Security > ** Monitoring > ** Integration with Apache Hadoop > ** Integration with other project > ** Upgrade? > ** Life cycle (services) > ** Common issues > > ============================================================================= > > > Thoughts, help and ideas welcome! > > > Thanks, > Bruno
