[Buildroot] RFC: Manual refactoring - Request for feedback before Buildroot Developer Days.

[Buildroot] RFC: Manual refactoring - Request for feedback before Buildroot Developer Days.

[Samuel Martin]

Hi folks, Buildroot users and developers,


The manual has been under discussion for refactoring for some months [1,2,3,4].
This rework concerns all aspects of the manual (organization/table of
content, and sections' content) [5].

In 4 weeks, the Buildroot Developer Days will take place and I am
pretty sure we will talk about it there [6].

Meanwhile, whatever who you are (BR-users, BR-developers,
BR-maintainers, newcomers or long-term followers, using BR in your
spare-time, or at work...)
we will really appreciate feedback about the current manual:
- what is good
- what is not so good
- what is wrong, or not up-to-date
- what is missing
- what would you like to see in the manual
- all existing material and way to gather them and make them easily
referenced and available for anyone looking for Buildroot
help/doc/tutorial/...
- anything else, remarks, suggestions...


If you feel concerned about Buildroot, its documentation, let your
voice be heard by:
- responding to this mail;
- or updating the Manual refactoring wiki page [5].


Yours,


References:
[1] http://lists.busybox.net/pipermail/buildroot/2012-March/051952.html
[2] http://lists.busybox.net/pipermail/buildroot/2012-May/053803.html
[3] http://lists.busybox.net/pipermail/buildroot/2012-August/056486.html
[4] http://lists.busybox.net/pipermail/buildroot/2012-August/057070.html
[5] http://elinux.org/Buildroot:ManualOrganization
[6] http://elinux.org/Buildroot:DeveloperDaysELCE2012#List_of_topics_to_discuss


-- 
Samuel

[Buildroot] RFC: Manual refactoring - Request for feedback before Buildroot Developer Days.

[Grant Edwards]

On 2012-10-07, Samuel Martin <s.martin49@gmail.com> wrote:

> we will really appreciate feedback about the current manual:
>
> - what is good

Good things about the current manual:

 1) It is available on line in a single HTML page.  Please, please, in
    the name of all that's usable, don't split it up into hundreds of
    HTML pages each with few sentences sentences and the dreaded
    "next, prev, up" buttons.  Having it on a single page allows you
    to search using the browser's "find" facility and makes it easy to
    skim through to find waht you want.

 2) The HTML version renders well at any window width.  Some manuals
    have code examples that force the the entire page to be rendered
    with with a line length that's hundreds of characters long -- the
    resulting pages end up being way too wide for easy use.

 3) It's writtenin asciidoc.

     a) Allows generation of a variety of formats (PDF, HTML, text).

     b) Makes it easy to read source and submit patches.

    Something like reStructuredText would also be fine.  I fear
    LaTeX's time has passed, and XML's time[1] has never arrived
    (hopefully it never will).

    [1] XML is fine as a machine-generated and machine-read format,
        but no human should ever be expected to edit it except in an
        emergency.

-- 
Grant Edwards               grant.b.edwards        Yow! Did YOU find a
                                  at               DIGITAL WATCH in YOUR box
                              gmail.com            of VELVEETA?