Canonical Voices

Posts tagged with 'documentation'

Colin Ian King

The Firmware Test Suite (fwts) portal page is the first place to visit for all fwts related links.   It has links to:

  • Where to get the latest source code (git repository and tarballs)
  • PPAs for the latest and stable packages
  • Release notes (always read these to see what is new!)
  • Reference Guide / Documentation
  • How to report a bug (against firmware or fwts)
  • Release schedule, cadence and versioning
Thanks to Keng-Yu Lin for setting this up.

Read more
pitti

Many libraries build a GObject introspection repository (*.gir) these days which allows the library to be used from many scripting (Python, JavaScript, Perl, etc.) and other (e. g. Vala) languages without the need for manually writing bindings for each of those.

One issue that I hear surprisingly often is “there is zero documentation for those bindings”. Tools for building documentation out of a .gir have existed for a long time already, just far too many people seem to not know about them.

For example, to build Yelp XML documentation out of the libnotify bindings for Python:

  $ g-ir-doc-tool --language=Python -o /tmp/notify-doc /usr/share/gir-1.0/Notify-0.7.gir

Then you can call yelp /tmp/notify-doc to browse the documentation. You can of course also use the standard Mallard tools to convert them to HTML for sticking them on a website:

  $ cd /tmp/notify-doc
  $ yelp-build html .

Admittedly they are far from pretty, and there are still lots of refinements that should be done for the documentation itself (like adding language specific examples) and also for the generated result (prettification, dynamic search, and what not), but it’s certainly far from “nothign”, and a good start.

If you are interested in working on this, please show up in #introspection or discuss it on bugzilla, desktop-devel-list@, or the library specific lists/bug trackers.

Read more
Daniel Holbach

We have achieved a huge milestone in the development community. For years we wanted translatable packaging and development documentation. It’s there. If you head to http://developer.ubuntu.com/packaging/ you can see the following:


The Ubuntu Packaging Guide (Spanish) – would you like to learn how to package or become an Ubuntu Developer? Here’s a comprehensive, topic-base guide that explores and describes the main concepts of packaging. It is available as


This is absolutely awesome. From now on we will be able to add languages and have up-to-date Packaging and Development docs available whenever they are complete enough.

This work was brought to you by many people who worked very hard to get all the bits right, both on the packaging, integration, beautification and translations sides. You all know who you are. Be proud of your work. This will ease the steps of many people into helping out with Ubuntu!

As always this is ongoing work and the great thing is, you can help out:

This makes me a very happy man and it’s great we finally got there. Now let’s get all the other translations up to scratch! :-D

Read more
Jussi Pakkanen

Say you start work on a new code base. Would you, as a user, rather have 90% or 10% of its API functions commented with Doxygen or something similar?

Using my psychic powers I suspect that you chose 90%.

It seems like the obvious thing. Lots of companies even have a mandate that all API functions (or >90% of them) must be documented. Not having comments is just bad. This seems like a perfectly obvious no-brainer issue.

But is it really?

Unfortunately there are some problems with this assumption. The main one being that the comments will be written by human beings. What they probably end up being is something like this.

/*
 * Takes a foobar and frobnicates it.
 *
 * @param f the foobar to be frobnicated.
 * @param strength how strongly to frobnicate.
 * @return the frobnicated result.
 */
int frobnicate_foobar(Foobar f, int strength);

This something I like to call documentation by word order shuffle. Now we can ask the truly relevant question: what additional information does this kind of a comment provide?

The answer is, of course, absolutely nothing. It is only noise. No, actually it is even worse: it is noise that has a very large probability of being wrong. When some coder changes the function, it is very easy to forget to update the comments.

On the other hand, if only 10% of the functions are documented, most functions don’t have any comments, but the ones that do probably have something like this:

/** 
 * The Foobar argument must not have been initialized in a different
 * thread because that can lead to race conditions.
 */ 
int frobnicate_foobar(Foobar f, int strength)

This is the kind of comment that is actually useful. Naturally it would be better to check for the specified condition inside the function but sometimes you can’t. Having it in a comment is the right thing to do in these cases. Not having tons of junk documentation makes these kinds of remarks stand out. This means, paradoxically, that having less comments leads to better documentation and user experience.

As a rough estimate, 95% of functions in any code base should be so simple and specific that their signature is all you need to use them. If they are not, API design has failed: back to the drawing board.

Read more
Daniel Holbach

Many engineering teams in the Ubuntu world have made extensive use of User Testing in the last years. This is an important reality check for everyone defining the experience of users. Do my assumptions still hold true? What do users expect? Are there use-cases we never considered? Which steps confuse our users?

The Ubuntu developers, so everyone who builds Ubuntu, integrates pieces to work nicely with each other, maintains packages and produces the distribution we all love, everyone is interested in this kind of feedback.

User testing of the Ubuntu Development process has, if it happened, always been ad-hoc and isolated. This is the reason why we want to look into this again and figure out which parts of the work-flows need to be improved.

Have you thought about contributing to Ubuntu Development before? Did you like the thought of helping improve the distribution millions of users love? If you did, you might be interested in this User Testing initiative. You will only have to read our documentation and send your feedback to Ubuntu Dev email. We in turn will make sure your feedback is put up for discussion and fixed eventually. Also will we will help you on your way if you should get stuck.

This initiative is not to be confused with mentoring. We are not going to do your homework for you or package your app. :-) Instead this will provide a great way for you to get started where you can share your experience with Ubuntu developers, who can help you along, while you provide valuable feedback. Your feedback will be treated confidentially and only published in an anonymised and summarised fashion.

What you need to do? Simple:

This is an experiment we will do until the release of Ubuntu 12.04 (April 26th). This should give us food for thought for the upcoming Ubuntu Developer Summit and depending on the success of the initiative, we will continue it.

Follow @ubuntudev on twitter.com, identi.ca, Google+ or facebook.com to find out more about this initiative and others.

Read more
Colin Ian King

I've now competed the documentation of the Firmware Test Suite and this include documenting each of the 50+ tests (which was a bit of a typing marathon).  Each test has a brief description of what the test covers, example output from the test, how to run the test (possibly with different options) and explanations of test failure messages.

For example of the per-test documentation, check out the the suspend/resume test page and the ACPI tables test page.

I hope this is useful!


Read more
pitti

As a followup action to my recent Talk about PyGI I now re-used my notes to provide some real wiki documentation.

It would be great if you could add package name info for Fedora/SUSE/etc., and perhaps add more example links for porting different kinds of software! Please also let me know if you have suggestions how to improve the structure of the page.

Read more