New essay: Trying to convince application developers to write API documentation

I’ve written a new short essay: Trying to convince application developers to write API documentation

I’ve created the Short essays page on my website. I plan to write more essays in the future, as short articles that can be read independently. Around the theme of programming best-practices. I’ll inform you on my blog when I publish a new essay.

Note, it’s unfortunately not written in ConTeXt (see this previous blog post), as I haven’t found a text editor for ConTeXt that just works and is easy to install, with all the features I’m accustomed to when I write a LaTeX document. So I fell back to using LaTeX.

2 thoughts on “New essay: Trying to convince application developers to write API documentation”

  1. There are two things you can do to make it happen:

    1. Give the developers lots of money to hire someone to do it for them. Better yet, give them even more money so there’s two documentation writers for a single developer. This is not gonna work anyway because even if you have corporate development backed by truckloads of funds, there are going always to be three things “we have no budget for”: QA, documentation, and the bloody coffee machine on the 6th floor.

    Go see Apple’s API docs, and you can poke around and find huge gaps in those docs. Outdated docs. It’s not a company that cannot afford it, mind you.

    2. Cancel the crunch time and kill the culture which demands gobs of code and features yesterday: move fast, move faster than those guys, ship it, ship it, shorten the release cadence, go go go already, work in non-stop sprints, do the weekly releases, build the excitement, and other such nonsense.

    All developers are acutely aware how important the documentation is, no need to preach to the choir there. The problem is, after they do their direct job, they usually won’t really have either time or the energy to do that.

    Oh, and there are few programmers capable of writing documentation that doesn’t suck.

    1. API documentation can (and sometimes should) be written at the same time as writing the code, so that the ideas are still fresh in the head.

      To such a work environment that you describe, I say no! I don’t want to work in such a situation. The nice thing with Free Software is that we *have* the time to do things right, to build solid foundations for tomorrow’s software.

Leave a Reply

Your email address will not be published. Required fields are marked *