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

[Christoph Haas]

On Mon, Jan 17, 2005 at 08:07:26AM +0200, Sean Wheller wrote:
> John stated he did not have the time for this a perfectly good
> explanation

That's one issue. And it affects me, too. But in this mail he said that
he "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".
I admit that this has changed lately. Just that not everyone has
noticed.

> I can't see the problem. The process of writing is still informal.

A lot has been accomplished lately and Enrico deserves a big "Thanks"
for his Wiki gardening. Our goals have become much clearer now. And I
hope that I won't have to read any more of the "shouldn't we rather
merge the A document with the B document". :) But still we are using
more technology than absolutely needed to accomplish our jobs IMHO.

> The docs are there, but nobody is writing.

Most members started with zero knowledge about DocBook and
repositories. They should be able to do their daily work with a dozen
commands to compile, validate, check in and out. We need as little
information and infrastructure as possible to get going. If I need to
worry more about learning the last features of Subversion and DocBook
then I'm kept from writing. Learning in the process is a good thing
though.

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

After a quick look most of them still are. And it's true that the
overall production has never been much.

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

There hasn't been a real plan. And things just did not work. But I felt
that every once in a while we all pulled together and said "okay, let's
keep it like this and start writing". Just a few days later someone had
new ideas. This happened once to often so that people now sit around and
seem to wait for the next boom.

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

Yes. The information on the Wiki has become very valuable. I was
surprised to see your effort that after one day we had a several screens
long explanation of DocBook syntax, validation and the like.

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

I have no experience with 'vendor drops'. Sounds like 'branding', right?
So you intended to check out the upstream (Gnome/Debian) documents and
patch them to read "Ubuntu" everywhere? (Put a little too simple.)

> > -- 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 think the authors are overcharged. When I started with svn and docbook
on the team everyone bit the bullet. I was asked for a quick
introduction on how it works and which the most important commands are.
I didn't say: just read the fine manuals about docbook and subversion.
Authors don't need to know everything about Makefiles either.

And of course we have psychological effects here, too. Nobody else
writes anything - why should I? (If everyone but me would be writing
then I'd get my butt on the chair and work late to not look like an
idiot.) Nothing has been written for months - why start today?

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

Agreed, the document needs to be syntactically valid. But the source
code files are just a tool for the team. The end-user won't see much of
it. So perfection should rather go into the content part.

> Would you expect broken code from the devel team?

Yes. After the fifth Hoary update in a row broke my notebook
installation. :)

> There have been problems and questions around the focus and scope 
> of documents. I think these have been largely sorted.

Yup.

> 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 can only speak for myself... but I always have some spare time to
spend. And I just haven't been motivated to commit anything. And it's
not because I like reading my own complaints.

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

I'm curious. But I think I don't have enough information yet. That's
what I found online:
http://svnbook.red-bean.com/en/1.1/ch07s04.html

Questions:
- how do we get the documentation into our structure?
- how do we keep in sync with upstream?
- which upstream documentation is available that fits our documents
  that we work on? (e.g. is the help file of every application in the
  "System administration" menu available so I don't need to rewrite it?)

Perhaps you can paint a virtual picture of how this would work for us.
I'm not experienced with branches either. Just the boring theory. :(

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

Thank you for not flaming back. :) If I didn't care I hadn't taken the
time to protest publicly. (I'd rather not think about how much content I
could have written during that time.)

Another proposal: looking at the current situation where hardly anything
seems to be accomplished; shouldn't we release the "chapter lock" for
authors and just allow everyone to commit everywhere? Or does that add
too much confusion?

Perhaps others add something about their motivation so we know where the
shoe pinches. Perhaps in half a year we all laugh about it and are
writing documents like hell. A man can dream. :)

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