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

Mon Jan 17 15:18:32 UTC 2005

On Monday 17 January 2005 13:14, Christoph Haas wrote:
> On Mon, Jan 17, 2005 at 08:07:26AM +0200, Sean Wheller wrote:
> > 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.

I agree, well done to Enrico!!!

As for changes, well I think the idea is to remain flexible and evaluate as we 
go.

As for technology, the problem is not the technology. Each technology we use 
is an enabler. At present we are not using more or less tech than is 
required. However, while technology is an enabler it cannot do the writing 
for us.

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

Again this should not be a problem.

I have offerred and am still here to support. I suggest everyone just work in 
small pieces and commit, commit, commit. I will sort out the problems as the 
commits come in. However, people must then not expect to learn anything. So 
if you can do svn commit, svn update and resolve diffs, I will take care of 
the rest and the advanced svn stuff. If this makes people comfortable, then 
great, let's go.

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

Yes and no.
More on this later.

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

No. The power of OSS is in the community. We all have skills, some are more 
common amongst us and some not. Point is we can get by. The problem in this 
is that the reality of OSS documentation does have certain requirements.

I don't have to make the business case for Docbook, Revision Management etc. 
Community has done that long ago.

Point is documentation is not easy, period.

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

Sorry but people that are thinking this way should sincerely evaluate why they 
are here in the first place. I know this statement is flame bait and warn I 
will not be responding to any results. But I believe it to be the truth. I 
certainly don't base my contributions on the pace or amount of contributions 
other make. OSS is based on "gift culture." Look at examples of gift culture 
and you will see they work because there is an abundance. Peoples status is 
gift cultures is not measured by what they own, but by what they give away. 
Each person decides what they can give away.

The problem with documentation is that it is a component that fits within the 
go-to-market stage of the technology cycle. There is no way to easily finance 
it by boot-strapping with developers and their customer projects. 
Documentation is about building a whole product and impacts on support and 
training costs.

Fact is developers can make cash from developing on OSS projects. Documenters 
can't. When last did you see a bounty to write documents or a part thereof?

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

I agree about the content being the main target hence my previous discussions 
in other threads about the relatively low importance of yelp. But if you want 
to use XML to build docs this by definition means conform to rules:
1. Well-formed
2. Valid

Choosing to ignore these rules is just asking for problems and the longer 
people choose to ignore the bigger the problem down the road. Please don't 
ask me to fix it at that stage. I don't mind in dribs and drabs if it 
elevates people from the problem of learning docbook. Hey for all I care 
write it in wiki and tell me to put it into docbook for you.

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

As before. Work small, commit often. Trust me you will be amazed at how 
quickly you will have achieved a great amount of work. You may also be amazed 
to find that somebody in the community has even enhanced on what you have 
done. Trust the community. Make your work transparent. The power of one is 
nothing compared to the community.

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

Dead on target :-)

However, I prefer to open a new thread on this. As I said in an earlier 
message in this thread. I have been experimenting :-)

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

There is no chapter lock. Just mark a section/chapter or what you want and 
hack it. Two or more people can work on the same section. The idea was just 
to see who could work on what and what was left, so that new people can find 
a place of their own.

-- 
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/1a938dec/attachment.pgp>