{Desktop 12.10 Topic] Holistic approach to Ubuntu documentation

Jo-Erlend Schinstad joerlend.schinstad at ubuntu.com
Thu Apr 19 01:51:06 UTC 2012


Den 19. april 2012 03:11, skrev Jeremy Bicha:
> Your topic mixes developer docs, entry-level user docs, and "power
> user" docs. Each of those needs a different approach and I think it's
> simpler to tackle them as three mostly separate things. Also, if
> you're going to discuss documentation, you should probably include the
> docs team (CC'd now) as that's where people interested in that read. 

The point is the exact opposite. We shouldn't split documentation up
into completely unrelated pieces. That is the problem. We should
consider it a whole. One single tree of knowledge. Before a release, we
should be able to walk the entire tree and make sure all documents are
Obviously Valid. You don't have to specialize in a single topic in order
to do that. It just requires effort, and for that, it must be obvious
what to do.

With different docs being at different places, organized in different
ways, maintained by "unrelated" teams and mixing versions, it's very
difficult to do any kind of quality assurance or to do anything in a
systematic way – as a whole.

But for documentation to be seen as a whole, related software must
sometimes also be seen as connected. That's why I replied here, since
Unity is my main example. It's not simply about documentation. For
instance, if I want to learn how to write a Python application for
Unity, I have to read this:

Unity-5.0
AppIndicator3-0.1
Indicate-0.7
...

They are obviously connected, but it's not at all obvious in versioning
or documentation. I'd like to see something more like Unity
Specification 1.0 Documentation, which would include those technologies.
I'd like to see a Vala/GTK implementation of the Dash, for instance. And
it'll have completely different versions than those listed above.

This means that we can't just adapt documentation to software, but also
adapt software to be more documentable in a way. I don't think this has
to be very difficult, but it requires discussions and decisions. Seeing
the bigger picture.

The desktop is the most visible, most important aspect in this regard.

Jo-Erlend Schinstad



More information about the ubuntu-doc mailing list