[proposal] Split User Guide (was: The "It's Just a Desktop Distro" Problem)

[Alexander Poslavsky]

On Wed, 5 Jan 2005 23:57:00 +0200, Sean Wheller <sean at inwords.co.za> wrote:

> In light of the original message posted by Matt (in its full length), I would
> like to resubmit my proposal to split the User Guide into User Guide and
> Admin Guide.
> 
> My reasoning:
> -----------------
> 1. Audience
>  There are two audiences:
>  a.) User = Desktop
>  b.) Admin = Server

I agree with the two audiences. But the current work of the
documentation team is only aimed at the first group. All our
documentation, Userguide, Quickguide and Faqguide, all these are only
meant for end-users.

> Problems I foresee:
> ----------------------
> 1. At present we have one book we need to decide what to split and redress the
> outlines of both books.

I do not see there is anything to split. The documents we are working
on at the moment are fine as thet are, there aim is end-user. Even the
administration-part is end-user-admin not server-admin.
 
> 2. In the interim I and anyone who wants to help should hammer out proposed
> outlines for User Guide and Admin Guide taking into consideration the current
> User Guide.

The user guide should be left alone for the moment. It is (more or
less) fine. I don't mind *adding* a server-guide.

> 3. We should then invite comment from marketing and devel. This will help us
> better define the outline and hence create better targets for us.
> 
> 4. We should agree on these outlines and prepare the Admin outline for when
> people have finished their current work.

This is a key-thought, we should finish stuff and only then continue
with new stuff. We have a deadine to uphold. We need documentation for
Hoary. User documentation. A Server-guide would be nice as a
place-holder for in depth stuff, *next* to the existing stuff.

> 5. When everyone has finished their current work and done their last commit,
> we will split the content in User Guide that should be in Admin Guide into
> the relevant sections.

As I said, the user guide should be left alone. It is fine as it is
and the admin-parts are end-user admin stuff. We could add links to
the server-guide for more in depth stuff though.

> 6. We should then realign ourselves so that we each know who is going to take
> what. I envision a list of the docs and their outlines with peoples names
> next to those sections people are or will do. Any sections without an owner
> can then be seen as places for new contributors, or current contributors who
> want to take on more or another section, to take ownership.

This is a very good idea.


> What do people think?

My conclusion:
1. leave user-guide as it is
2. add a server-guide
3. make a list of who does what

greets, AP