What are we doing wrong?

[Jim Campbell]

Kyle,

On Tue, Jan 19, 2010 at 4:46 PM, Kyle Nitzsche
<kyle.nitzsche at canonical.com>wrote:

> 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
>
>
I think much of what you are trying to do can be done with a new Gnome
syntax, Mallard (see projectmallard.org ), or (evil of all evils) DITA.
 Trying to hack something that is book / chapter / article focused like
DocBook into a more topic-oriented, modular format doesn't seem like the way
to go when there are other options out there that can do what you want

DITA is really built to do what you are trying to do, but it is a PITA (ha,
get it) to author in (especially if you don't have any fancy authoring
tools).  Mallard is being actively developed, and is growing in leaps and
bounds.  It is super-easy to author in Mallard.  It is easy to add plug-in
style supplemental help (think docs for custom plugins or OEM-specific
content) in Mallard.

Shaun McCance is organizing a desktop help summit in Chicago in March (
http://is.gd/6DS7x ).  Is there any chance that you can attend?  It sounds
like your Canonical-related documentation needs are kind of on the
leading-edge of where desktop Linux docs need to go, so it would be good to
get your input.

Jim
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20100119/da20a2c1/attachment.html>