Re: Documentation overhaul

[Konstantin Boudnik <co...@apache.org>]

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

Re: Documentation overhaul

[Sean Mackrory <ma...@gmail.com>]

I would love to use something markdown-like, although as I think I've
previously said I really like the minimalist-yet-professional-looking style
that HBase has, having used the stylesheets from the FreeBSD manual.
Content-wise, I think I'd like to start writing a chapter on using the
various package managers, and maybe some sections that cover the various
families of distros we support and the major differences to be aware of
between them when developing or using Bigtop.


On Tue, Apr 8, 2014 at 3:08 PM, Konstantin Boudnik <co...@apache.org> wrote:

> 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
>