I love the approach of “change the code, write the documentation”; the code author is in a unique position to be able to explain the new behavior of the system.

I love the approach of “change the code, write the documentation”; the code author is in a unique position to be able to explain the new behavior of the system. However, most FOSS projects could benefit from a technical writer, who can improve these first drafts to make them more usable. Back in the Stone Age, companies like IBM had vast writing staffs. As a result, you got entire walls full of documentation. For OS/360, you got Concepts And Facilities, that explained what the software did for you; you got reference manuals; and Program Logic Manuals, which explained, in exhaustive/ing detail, how the program worked (with flowcharts!). Arguably, the software I use today is far more complex than OS/360; yet we don't see the same attention to organization and detail in the documentation. I understand the reasons: IBM's dead-tree wall relied on paying tech writers, and that's incompatible with the tiny budgets most FOSS projects suffer. Far too often, I will go to a FOSS site's documentation page and discover a mass of links to pages that explain how to build the program on Itanium, or why this program is better than another one, with no walkthrough of “how to use this program for a typical case”, or even “if you want to do this kind of operation, these are the pages you need to read”. Often, the documentation isn't included in the repo, which lowers my confidence that the documentation and software are updated in step. So I celebrate projects such as PostgreSQL, Emacs, and Arch Linux (for the wiki)—there are many more—where there is a real effort to create good documentation, even when I think that documentation can be improved or reorganized. Let's not allow the perfect to be the enemy of the good.