bigtop manual: how will the contents evolve?

[Jay Vyas <ja...@gmail.com>]

Hi bigtop!

Just curious because  don't see any substantial contents in the docbook
yet, so wondering how it will evolve. Where will they go and how should the
bigtop folks contribute to them?  I'm dont know much about docbook and how
docbookX is meant to be used here, but it looks like a cool way to
propogate docs in the code.

Itree -hs
.
└── [ 204]  site
    ├── [ 170]  docbookx
    │   ├── [2.8K]  apache-bigtop-user-guide.xml
    │   ├── [1.1K]  customization.xsl
    │   └── [ 170]  userguide
    │       ├── [1.3K]  introduction.xml
    │       ├── [1.2K]  preface.xml
    │       └── [1.3K]  what-s-new.xml
    ├── [ 170]  resources
    │   ├── [2.1K]  bigtop.rdf
    │   ├── [ 136]  css
    │   │   ├── [3.7K]  freebsd_docbook.css
    │   │   └── [1020]  site.css
    │   └── [ 170]  images
    │       ├── [4.1K]  apache-incubator-logo.png
    │       ├── [1.0M]  bigtop-logo.ai
    │       └── [ 15K]  bigtop-logo.png
    ├── [3.6K]  site.xml
    └── [ 272]  xdoc
        ├── [5.4K]  index.xml
        ├── [1.5K]  irc-channel.xml
        ├── [1.6K]  issue-tracking.xml
        ├── [3.0K]  mail-lists.xml
        ├── [148K]  release-notes.xml
        └── [6.3K]  team-list.xml

Thanks and great work on creating a framework for code-based, human
readable documentation :)

-- 
Jay Vyas
http://jayunit100.blogspot.com

Re: bigtop manual: how will the contents evolve?

[Bruno Mahé <bm...@apache.org>]

On 12/11/2013 08:36 PM, Jay Vyas wrote:
> Hi bigtop!
>
> Just curious because  don't see any substantial contents in the docbook
> yet, so wondering how it will evolve. Where will they go and how should
> the bigtop folks contribute to them?  I'm dont know much about docbook
> and how docbookX is meant to be used here, but it looks like a cool way
> to propogate docs in the code.
>

Right now, there is no content :)

The way it works is:
* src/site/docbookx/apache-bigtop-user-guide.xml is the main entry point 
to the user guide. If we were to add another guide, we would simply 
create another similar file in that directory.

* You could put the entire document in that file 
apache-bigtop-user-guide.xml only, but for obvious reasons I split it in 
multiple files and import them through xi:include.

* Therefore each chapter of the user guide can be found in 
src/site/docbookx/userguide/. If a chapter gets too big, we could always 
split it again in multiple files



So any contribution should mostly go into one of the file dedicated to a 
chapter.
Regarding the content itself, in order to keep it organized I have put 
together a proposal for the list of chapters.
See my email about the documentation overhaul.
My plan is to add information here and there according to the list of 
chapters. I don't see any reason to work chapter by chapter.
So feel free to pick a chapter or a section and start sending patches.
Try to keep them small so they can be reviewed without too much troubles 
and also less chance for having patch stepping on each others. Also 
english is not my mother tongue, so I don't mind patches improving 
sentences.
So my main recommendation is to stick with the plan. Beyond that, any 
part is fair game if you want to contribute a paragraph or even just a 
sentence. Any help is welcome!


I will also volunteer to push the website on a regular basis so changes 
becomes visible without too much delay.



Thanks,
Bruno