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

[Sean Wheller]

Thanks John for that interesting and honest explanation. Having read this made 
many things much clearer in my mind and got me thinking. Here is what I 
think.

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. In addressing the situation I will make an attempt to perform 
this task on-the-fly and at a very late stage. I am not sure it will be a 
conclusive and all encompassing attempt, that would take much more than an 
email, or that it will help, but let's see.
Since I have not been with the project long, please consider that my points of 
view may be well-off target. If so please just say so, I have the skin of a 
Rhinoceros so promise I won't be offended. While some of what I will say is 
based on my experience thus far, other parts are based on my 'gut' and 
experience. The later of which I trust more than intellect sometimes. 

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 was 
equally confused by the intended duplication of work process, the method of 
once in wiki and then port it to DocBook seemed less than efficient. I was 
surprised to see outlines in the docs but no meat and started questioning 
this approach. I now understand the reasoning, but still feel that the 
process is flawed. However, I think this is a community thing to change and 
push no further.

What I expected to find was a documentation set that included: User Guide and 
Admin Guide that contained the docs I found scattered across the wiki. These 
works would have various upstreams as dependencies. In essence these books 
would be patches on the vendor drops from GNOME and Debian primarily. The 
patches would essentially customize texts to fit the context and nuances of 
Ubuntu and enhance where vendor drops had a deficiency. Those deficiencies 
could be patched back to upstream.

However, this was not the case. It became apparent to me that people had the 
intention to write these docs from scratch. Already in a position where I was 
making intrusive changes to the DocBook framework, I raised this concern but 
not with my usual over powering passion. Perhaps I should have stuck to my 
guns, but that would have risked making more people mad at me than already 
are, but enough politics.

I still believe that a User Guide is a worthwhile project, though not as you 
originally intended as a publication for training. In my experience training 
materials are a different animal to guides. As a book it should target the 
user and as such be scoped to discuss the Ubuntu implimentation of the GNOME 
Desktop. Where to find things, what they are for? Kind of like a 'Getting 
Started' Chapter of a user manual. Here is the menu and these are the options 
available. Here is the basics to installing more. From there it would be 
GNOME docs (only those installed by default).

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

How to implement this? I envisioned using SVN and a method called 'vendor 
branches' (or vendor drops). I discussed this on IRC and was advised that it 
does not work and that vendor drops would be difficult to manage 
considereding the current level of proficiency team members had with SVN. I 
dropped the subject.

On the side I have been playing with vendor drops to see if it actually works. 
So far I have not had any problems and have two recommendations where people 
have used it successfully. Both methods have their twists, but result in a 
working vendor drop on which to build. Since I am not through testing this, I 
cannot conclusively say it will work in production. But I am reasonably 
confident that it will. Only by testing in a production environment will we 
know for sure. If John is willing to test it on a side repos, I am willing to 
help.

This said, it may be a way for the team to significantly advance the doc 
development and reduce work load now and in the future. In addition, as 
hinted before, it provides the opportunity to feed vendor drop changes back 
upstream. The doc team would therefore be contributing on Ubuntu and Upstream 
docs.

This method of development seems instinctively better considering the 
composition of Ubuntu.



-- 
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/20050116/7d10e878/attachment.pgp>