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

[Sean Wheller]

On Monday 17 January 2005 01:05, Christoph Haas 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.

John stated he did not have the time for this a perfectly good explanation, I 
quote from his message:
"I would like to let everyone know why I have not been around much.  
When I started helping, I worked about 20 hours a week, and that was 
it.  I have always had kids and a wife but when you only work 20 hours, 
there is alot more time for them and other things.  Since November I 
have been working 40-50 hours a week at a new job,  I also still have 
to manage the kids and wife."
 -- From: 
John Hornbeck To: ubuntu-doc.at.lists.ubuntu.com Date: 
2005-01-02 23:48

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

My thinking is that this is because of a "a basic
lack of requirements and operational analysis."

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

I can't see the problem. The process of writing is still informal. The only 
formalities are to validate docs and add authorblurb. Both are simple and 
aimed at making life easier. The docs are there, but nobody is writing.

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

My first commit was on the 28/12/2004. Prior to this there were exactly 6 
commits to SVN, all made on the 27/12/2004. The files in SVN were empty of 
meat. They were an to a large degree still are outlines. Evidently work was 
done in wiki, which is still an option.
At this time I was still trying to patch the project together in my mind. I 
could not understand most of what was going on or how things worked. To cut 
it short I found the barrier to entry very high. Not because of Docbook, but 
because the information on wiki did not say this is what you you need and 
this is where things are and this is how it works. I hope that, with the 
current changes to wiki, furture contributors will find it easier.

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

Every project in OSS has some management. Some more, some less, but management 
there is.

>
> > 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. :)

OK, we agree in part. I think the point of OSS is to copy. In my post I 
outlined a way to do it. Do you think this will help?

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

The operative word here is *intended*. I have asked and read about QG since 
this was the priority. My thinking is that by building the UG, and creating 
the QG as an abstract of the UG, we will be killing two birds with one stone.

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

Agreed. Yet, I dont think the problem is formalization in this case. It is 
done in the same way you always did it. You write a section and commit it. 
Nothing formal about it. Or perhaps I fail to see what you and John mean by 
formal and in this case ask that you please provide examples.

> 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!). 

The focus is on doing docs. All people need to do is write and there will be 
content. As for quality, I don't  know about the rest of the team, but when I 
put my name into a public space I want the quality to be good. At as best it 
can be under the circumstances.

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

A valid docbook structure is important for a number of reasons.
1. It ensures that problems can be avoided.
2. When problems to arise, they can be easily isolated.
3. We are preparing an open source code, other need to use it, give it to them 
in the way it is intended. 

Would you expect broken code from the devel team?

Communication is the basis for OSS projects. Especially on documentation. Each 
person should make a balance between writing and discussing.

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

Not if people commit their conntent. The structure of the docs is not 
unchanged. There have been problems and questions around the focus and scope 
of documents. I think these have been largely sorted. For the past wee or so 
I have constantly wondered why there are so few commits. I don'tthink the 
problem is framework changes or formalization. I just think that people are 
to busy after the break and find little time. This is natural in OSS.

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

Fun yes, hardwork too. I agree that there should be dedicated resources and 
contributive resources. As far as sorted out, I think it has been for a long 
time. As said before, the structure is the same all people need is to 
contribute. This can be don ein two ways, on wiki or in Docbook.

In light of the fact that people seem to be stuck or not sure which way to go 
I have made the suggestion to use vendor drops (90% vendor - 10% Ubuntu).

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


May I just say, that I am happy you have reacted. Your passion is a good 
thing. I would rather have people voice their problems and discuss it, than 
silence. Thanks for sharing.
-- 
Sean Wheller
Technical Author
sean at inwords.co.za
http://www.inwords.co.za
Registered Linux User #375355
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20050117/79ed00d4/attachment.pgp>