What are we doing wrong?

[Kyle Nitzsche]

Matthew East wrote:
> On Tue, Jan 19, 2010 at 7:37 PM, Kyle Nitzsche
> <kyle.nitzsche at canonical.com> wrote:
>   
>> I think such a "Getting Started" article is perfectly applicable to Ubuntu:
>> * overcoming any fear factor of a new OS
>> * enabling quick user success for doing a very few essential/first things
>> * pointing/linking to other help/web pages/wiki/forums, etc.
>>     
>
> {snip}
>
>   
>> Contents might be:
>> * welcome to Ubuntu!
>> * connecting to the internet (simple case: that is: point to the network
>> manager icon)
>> * getting around the desktop (where are applications, system stuff)
>> * which apps?
>> * adding apps
>> * updating software
>> * getting more info/help
>>     
>
> I think probably these are goals that would be well suited to the "New
> to Ubuntu" article that we include in our documentation. I agree with
> you that the article in its current state doesn't really serve much
> purpose and is more likely to be scary to a new user than helpful.
> This might be a way to introduce some more basic topics, while linking
> to other areas of the docs too.
>
>   
Matthew: did you check the prototype? Please do: it is a serious 
prototype, albeit written in a couple hours and with lots of room for 
improvement. It is  a docbook article (presented as html, with 
doctemplate default styling).

I've also just added to the following web page a tarball with the 
localized docbook version with a README for launching in Yelp.

http://people.canonical.com/~knitzsche/ubuntu-getting-started-guide/index.html

> If then we are interested in loading such an article on first login,
> then it could be done simply by calling "yelp ghelp:newtoubuntu". As
> to whether we do that or not, I think that we should discuss it with
> the desktop/usability team as there are clearly some competing
> arguments on both sides.
>
>   
Yes, this sort of thing it could certainly be part of ubuntu-docs and be 
launched on first-use start-up: those goals are not contradictory.

But if the Getting Started topic is folded into ubuntu-docs, that means 
I face more difficult options when reaching a solution with OEM clients. 
Whereas if it is a separate project on which ubuntu-docs depends, I can 
say to our clients: Hey, we already have a Getting Started topic that 
launches on first boot and we can make it right for you without having 
to fork ubuntu-docs! (The user experience is identical, I believe.) We 
just fork *that one small* pkg!

So, I'd like to bang the drum again: ubuntu-docs is unnecessarily big 
and monolithic:
 * It takes too long to load content at run-time, but if it were chunked 
into topic packages, the load-time for each would be less.
 * It is a large application with many interlocking parts that is 
difficult to modify and therefore it limits experimentation and improvement.
 * It 's hard to customize, and ubuntu has more and more customized 
versions (which we want to see succeed!).
 * If one bit of ubuntu-docs must be customized, it requires a fork to 
the whole pkg, and the customized fork can't be updated without creating 
patches, carrying them, and manually applying and releasing them.
 * Not every case wants the Ubuntu Help Center, but they might want some 
of the content, which is now hard to do.

I think it is time to take seriously the idea that the ubuntu-docs team 
manage multiple sub-packages of ubuntu-docs. I am not saying this is 
trivial, nor that it should be done without planning. But I don't think 
it is  *that* difficult. Each could get a launchpad project. Ubuntu-docs 
pkg would depend on each of them so they all get installed when 
ubuntu-docs gets installed. Ubuntu-docs package itself is reduced to a 
TOC function. Each topic package would install its own content and omf 
files. Each is individually buildable (into the usual suspects; 
localized docbook, and html and pdf if desired). The decision could be 
taken whether to translate them in the launchpad Ubuntu project, or in 
their own LP "upstream" projects (but released in a way that's 
synchronized with the release schedule, like the UNR packages have 
been). Yes, this makes it slightly harder to get source and understand 
the source layout, but these are relatively small items, I think.

cheers,
Kyle