Devouring Documentation

I just finished reading Federico’s Making GNOME Fast slides. Great stuff, honestly. But I predict that, in one year’s time, these slides will be lost to all but Federico and Google. Presentations are wonderful. They get the word out to large groups of people at once. They get people excited. They’re effective in the short term.

For the long term, our information needs permanence. We need to encourage people to write stand-alone documents like “Making Programs Fast”. Then we need to put them somewhere. Here’s the idea:

  1. Somebody create library.gnome.org already.
  2. Make user documentation not suck. See Project Mallard.
  3. For every library in our stack, have a complete API reference as well as good high-level documentation.
  4. Write a core set of developer guides.
  5. Put information like this into stand-alone documents.
  6. Put it all on library.gnome.org.

A good rule of thumb is that documentation should be definitive. If somebody wants some information, point that person to the place in the documentation where it’s provided. Is the information not in the documentation? Go update the documentation, then point the person to it.

Creative Commons Attribution 3.0 United States
This work by Shaun McCance is licensed under a Creative Commons Attribution 3.0 United States.