Nutshells, books and FAQs

[Sivan Green]

Christoph Haas wrote:

>Hi, friends and foes...
>
>Looks like we get ourselves organised well now. But there's one issue
>left I wonder about. We are currently working on the FAQ where we put
>topics from the Wiki in. Then other people (I just know of John) are
>thinking about the "Ubuntu in a nutshell" which is sometimes referenced
>as the "Ubuntu Book". What now?
>  
>

We should be concentrating on a tight list, of not so many items to 
accomplish for Hoary :) And ofcourse have people take up on what they 
like and do it.

>I have just looked at what documentation Debian provides. And besides
>the huge Debian Reference and the Debian Policy there is a number of
>documents that all deal with non-development topics. I could imagine we
>put all our effort together into a single document. Reading through our
>current FAQ (besides that it needs some style review) it seems like all
>the subjects could as well fit into "The Book". Look at the User's Guide
>Debian has taken from Progeny.
>  
>
This sounds very reasonable. I would love to see everything organized in 
a one source, with good indexing and maybe some search infrastructure to 
ease of finding information.

>Perhaps other people are already clear about the direction we are
>heading. But I'm still confused. And putting together such a large
>document is a lot of work. I would really like to avoid double-work and
>make sure everybody knows what should get in there.
>
>So my suggestion: can't we abandon the FAQ and change the
>"question/answer" style to regular sections within the <book>?
>That way we had a single document with everything in it. It could be
>used as an FAQ or just be read sequentially as a book.
>  
>
I propose we try and take the layout and toc hornbeck has been workin 
on, and see how we can combine it together with the FAQ layout to 
produce the first outline for the "Ubuntu Handbook".

>I know there is a bounty on the "nutshell" task. Honestly I'm not
>interested in bounties. So this is not meant to take any money away.
>I just fear that we will change our minds once the book gets started.
>
>Just tell me I'm writing complete rubbish. Otherwise this is how we
>could get started:
>
>- Consensus on the structure
>- Distribute chapters/sections across volunteers (least interference)
>- Put the current Q/A into an "old" chapter
>- Everybody gets the current Q/A out and moves them to their chapters
>
>I admit that this would probably be even more work than just Q/A. And we
>certainly do not need to explain the basic things time and again -
>pointers/links should be sufficient. But I would feel more motivated to
>write more complete and precise articles instead of just collecting bits
>and pieces.
>  
>
Seconded. The bits and pieces nature of the wiki already starts to show 
it's drawbacks, and a roughly small list of action items should be taken 
IMHO to fill in the big picture in the Ubuntu documentation. If this 
list is agreed here, I would take it up to the Wiki and create a top 
level page for work we agree to work on for hoary:

  1) Produce the "Ubuntu Handbook/User's Guide" and when we say "User's" 
we mean it's for the user, so no problem if we get slightly redundent 
wrt the wiki or other sources.

 2) Fix and improve the already shipping docs with the system:
       2.1 : Ubuntu shipped manual pages should be modified to reflect 
the actual system. see this to understand what I am talking about - 
https://bugzilla.ubuntu.com/show_bug.cgi?id=3353. We might need to ask 
devs to follow also on this, as being the sole responsibility for packes 
, as well their included man pages.
       2.2 : GNOME documentation, mainly the gnome-user-doc should be 
split to parts on which people step up and take certain sections and 
ubuntuize it , that is make the neccesary changes for it to support the 
Ubuntu Desktop look philosophy looks and quirks. I can think of doing 
this also to other already shipped software like GDM which might need 
some doc changes to include it's way of working in Hoary/Ubuntu etc..

3) Officially declare the Wiki as the "Last minute, README.TXT style" 
sketch pad that should be reduced to such, avoiding us investing too 
much time on it, whilst still providing for good purpose of outlineing 
new ideas, thoughts on, measure  work in regard to inclusion in the 
"main" stable documentation. We could make one page as acting the 
README.TXT for the system, putting here all the howtos and workarounds 
that are relavent to a specific release.


Keeping in mind that Ubuntu is a desktop user oriented system, we might 
give more attention to (1) and (2.2) and keep the others as on ongoing 
work...


>And I would really like to have Matt Kirchhoff involved in this because
>we really need someone to watch the work from the above.
>  
>
Yes, he already noted about his experience on that, so he would make our 
first guy to be maybe on the documentation test team, and can even be 
the main contact on that, to be working on with the people who expressed 
interests in testing the docs.



I would like to take all of this and make it a new wiki page, which is 
our workplan for the release, so please people , comment suggest, so we 
can reach consensus regarding this and really start working.

After we agree on this action items, enrico or I could make up a table 
with respective work items and people would just go and list themselves 
there, each one in the area he would like to work on. (thanks to ChrisH 
for offering that)


Many thanks!


Sivan