Documentation. Documentation. Documentation!

As I was rereading Ivan Frade’s blog post about the class-signals feature that me and Ivan developed for Tracker last week I got reminded of something I wrote a long time ago:

In my opinion, there’s nothing as important as developer documentation for a framework or library.

Ivan decided to ~ dump our internal planning document on GNOME’s Live wiki service. He didn’t write the document so he’s of course not to blame, but the document was in my opinion not suitable as end user framework documentation. Application developers should not be required to understand what goes on in our team’s minds. So I rewrote this.

You can find the document at the SignalsOnChanges page. Let’s see if starting next week I can convince the other team members to document their new features in a similar way. Many new things in Tracker’s experimental branch could use more clarification and examples.

I happen to believe that undocumented libraries and frameworks aren’t meaningful. That’s because letting it remain undocumented the developer renders his work utterly irrelevant for a serious application developer. I also believe that undocumented infrastructure software is worse than no infrastructure software.

I strongly recommend to application developers to refrain from using any piece of undocumented library or framework. Don’t lower yourself to their standards. Demand documentation by refusing to use undocumented infrastructure. Doing it as free software is no excuse for delivering extremely low quality, like what undocumented infrastructure is (in my opinion).

Thanks to Ivan’s blog post for reminding me of what I once wrote, and today still believe in, myself. While passionately coding new features you sometimes forget about this.

Which is unacceptable.

3 thoughts on “Documentation. Documentation. Documentation!”

  1. on the whole I agree with you.
    Sometimes though an immature branch is just too inviting to miss up :)
    A developer *could* spend upto 10x as long documenting a process from inception to completion and find that branches of that code never stay in the library.

    For many years now I have watched the documentation for the Microsoft dot net framework evolve from its early beginning with basically nothing but auto docs on the library upto something approaching the quality of the MSDN supplied around the classic visual studio applications.

    The problem with fledgling frameworks and libraries is that good documentation is built up from usage cases and explanations which seem natural now did not present themselves whilst constructing the class.

    There is also the problem of developer skillsets, someone versed in C or C++ may not produce good documentation.

    Obviously if you are employed to write to a predefined spec and part of that spec is documentation it is a different story :)

  2. While this is very true, it would be better to document it as part of inline api-docs and not on a wiki. History has shown many times that its hard to keep this in sync if the docs are not pulled from the sources. I know that you love gtk-doc, but once doc build is setup, its managable, right.

  3. The linux kernel has many undocumented features… it’s still awesome :)

    The documentation is the code… which is clean, simple, elegant and logical. I prefer an API with all those features over documentation any day.

Comments are closed.