Nutshells, books and FAQs

[Sivan Green]

Hmm, I guess not much people did see this post, so here it is again - 
You're comments are desried!




Sivan Green wrote:

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