Developer Documentation feedback

Dylan McCall dylanmccall at gmail.com
Tue Mar 3 17:39:17 UTC 2009


> Hi everyone,
> 
> I am interested in gathering feedback on the state of our developer
> documentation. I just don't want feedback from doc people but from
> Ubuntu developers themselves who have been consuming these docs.
> Currently the developer link from ubuntu.com points people to this
> page: https://wiki.ubuntu.com/UbuntuDevelopment
> 
> This page covers an immense amount of information about all aspects of
> Ubuntu Development. Mozilla has a "Mozilla Hacking in a Nutshell" page
> that caught my eye in a format that looks useful:
> http://www.mozilla.org/hacking/
> 
> I am wondering if perhaps we should have a more focused set of pages
> that makes it easier for people to drill down into a specific area of
> development as opposed to "One Big Page" or if we should start looking
> at something a bit more structured? I've heard many developer-friends
> of mine (who are not involved in Ubuntu) say that they wish Linux had
> an equivalent of the documentation that is in something like MSDN
> because they can never find anything and get lost in a bunch of wiki
> pages.
> 
> Mainly, I am interested in getting feedback on how we can knock down a
> barrier to entry-level people who might be interested in doing their
> first contribution to Ubuntu, the UbuntuDevelopment page feels
> intimidating to me. Yes, I realize that there's only so much one can
> do in making a complicated task simple and the answer might be
> "there's no way to explain this any simpler".
> 
> -- 
> Jorge Castro
> jorge (at) ubuntu.com
> External Project Developer Relations
> Canonical Ltd.
> 

I completely agree, Jorge!

One issue with building software for Ubuntu (or GNOME, Debian or Linux
in general) is that we lack Definitive "official" APIs for certain
tasks. If someone searches "flexible multimedia framework for Linux" he
gets piles of options that tend to be /supported/ by all sorts of
distros, but are only really great choices for a select few.

I think we need a nice, cleanly written "developing for Ubuntu" guide
that goes over the different APIs for tasks like file handling,
launching applications, creating GUIs and rendering high end 3D
graphics. IDEs and build systems would also be really worthwhile. It
should cover the specific technologies and methods that are well
supported in Ubuntu, that are maintained in the repositories and are
native to the desktop environment. Indeed, there are always choices like
jack vs. gstreamer for audio, but in that case I think writing from the
perspective of this one operating system could benefit in providing the
reasons for each without seeming too complicated.

Being specific is the key, of course; we have generic documentation all
over the place, but the definitive answers from more pointed
documentation would really help new developers.

Naturally, we wouldn't want to exclude other projects or to make Ubuntu
some kind of outlier in the Linux ecosystem (aside from the fact that
it's an awesome distro). This sort of thing should be very clear about
the things in use, and (if the reader wants to know) where they come
from and where else they apply. It would be nice if it had quiet, out of
the notes about choices optimal for interoperability, upcoming stuff and
what other distributions do, but the main text should generally stick to
one way of doing a particular task.

As I fiddle with development in Ubuntu, I try to keep a little list in
my mind of parts that really need documentation like that. Canvas
libraries and build systems are a big one. I'll try to write those
thoughts on paper from now on :)


Bye,
Dylan
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 197 bytes
Desc: This is a digitally signed message part
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20090303/7eb7d87b/attachment.pgp>


More information about the ubuntu-doc mailing list