Strategic Refocus (was: Difference between the User's Guide and the Gnome User's Guide)

[Christoph Haas]

Hi, there...

Please allow me to comment on some random quotes from John and Sean in
this thread.

-- John wrote:

> I had no contacts with anyone from gnome.  Let me give the history of
> this guide.  It was going to be a book which I was going to write for
> publication first. [...] Chris Haas than was suggesting to make it the
> project that the whole docteam would work on instead of a FAQ and the
> book.

I start to regret having it taken to the Doc Team because I feel that if
John had done it alone it had been finished already. Although seeing it
merged with the FAQ Guide is working great. plovs is doing a good job
there.

> In all honesty I lost interest in doing most of this because of no one
> being able to decide what we needed to do and everything getting
> changed constantly.

Same thing that ticked me off.

> We worked fast and got a lot of good docs done. Now it is all to
> formal of a process and everything has to go to commity before being
> done and people don't want to do things the same way. I am sad that it
> became this way, and I hope everyone works it all out because I know
> it stopped being fun for me.

Seconded. If you ask me 'people' still want to do it the same way just
that the whole process has been formalised to death.

> Sorry to go off on all of that but I needed to say it.

Actually I'm very glad you wrote that. Whenever I brought this up it
sounded like "sheesh, it's Chris complaining again".

-- Sean wrote:

> The basic problem in Ubuntu documentation seems to have been a basic
> lack of requirements and operational analysis. The results of this are
> now becoming more evident.

Please <excuse> my harsh words... but this is ridiculous. "Requirements
and operational analysis" sounds like complete management bullshit.
</excuse>

Let's put it like this: the Doc Team hasn't been doing things very
professionally (not enough coordination, syntactically incorrect
docbook format) but at least it has produced something. Now everything
is formalised but everybody (except plovs) has stopped writing content.
Your view of 'evidence' seems to differ from mine. You sound like my
boss... if it doesn't work we need more management. No, we don't.

> On first look at Ubuntu Documentation Project I was confused as to why the 
> project tried to redo so much that was already done. It seemed to be that 
> Ubuntu is based heavily on two major upstreams: Debian and GNOME.

I think you got a point here. We should be very careful that we don't
copy everything. As I'm writing the 'system administration' part of the
User's Guide I find myself rewriting a lot of stuff that is already in
the online help of the respective applications. Perhaps this is only a
problem of the menu items dealing with system configuration. I could
imagine to rather write a short introduction of what each application is
supposed to configure and then tell the users to read the online help.
After all it would then come close to the Quick Guide. :)

> For the Quick Guide I envisioned an abstracted version of the User Guide.

Don't think so. The Quick Guide was intended to be a collection of
"cribs" about the applications so people know what their purpose it and
how to use them basically. More like a dictionary of applications than
a book that you read from the first to the last page.

-- General words

The Doc Team's most important task is to write end-user documentation.
Instead we have been talking it to death and formalised so much that
hardly anyone seems to know what is done how. And I start to think that
I would rather provide third-party documentation for Ubuntu than spend
time in a "100% professional getting nowhere" team. I haven't surely
lost my interesting in writing documentation because I have two other
tutorials currently on my table. Just that our current modus operandi
is making me go bonkers. We shouldn't be talking about O'Reilly-style
books, training and certification. We should get some visible work
done (content!). No end-user cares about our docbook structure. They
expect helpful documentation. If only we had invested half of the
effort into contents that we spent talking, defining, formalising...

When Hoary will be released we will have a perfect Subversion
respository with all bells, whistels, trunks and branches. We will have
a perfectly valid docbook infrastructure. We will have lots of Wiki
pages about who we are, what we are (supposed to be) doing, about
protocols and regulations. We have so much "meta documentation" that I
needed to hire a lawyer at my desk. Still Hoary will probably not ship
with a single complete document (unless Alex finishes the FAQ guide
until then because he appears the hardest working content contributor at
the moment). And it would be intentional ignorance (the worst kind)
to keep 'business as usual' while we don't even have a working doc team.

I'm tired of complaining (that's the good news). I agree with John that
I like to have this sorted out. It's not fun for me any more either. And
voluntary work needs to be fun. Otherwise ask Mark if he is willing to
pay for the Doc Team members and find people who are willing to do it
like this for the sake of bucks. I have annoying tasks at work and
accept them because I need to earn my bucks. But during spare time
it is my choice to contribute here.

Enrico, Sivan, the rest of you, care to add your thoughts?

Regards
 Christoph
-- 
~
~
".signature" [Modified] 3 lines --100%--                3,41         All