Blog posts are no replacement for documentation

Since I was asked in a previous post I’d like to make some notes about why I “document by blog post” in so many occasions.

I know perfectly well that my blog posts are no replacement for proper documentation; code, procedures and policies need to be properly documented, and tied to the project they are supposed to document. Documentation by blog post is difficult to write, manage and search, and can be indeed useless for the most art.

So why do I write it? Well, most of the time I start a blog post with some ideas in mind, write down it, and then depending on the feedback I either continue the topic or drop it entirely. I guess the most prominent counter-example is the For A Parallel World (which I know I haven’t updated in a while).

Writing proper documentation is important, and I know that pretty well, I have written and ranted about that before as well. And it’s knowing that, that I started the Autotools Mythbuster project which, to be honest, has given me mixed feedback, and satisfaction. The problem is: writing a blog takes just a modicum of effort, because I don’t have any obligation about form, or grammar, or language; I might soft-swear from time to time in a post, I might rant, I might have some smaller mistakes around, both in grammar and content, and so on. I don’t go updating blog posts to fix grammar and style and so on. Writing complex and organized documentation requires a lot more work, and when I say a lot I mean quite a lot more. Of course the result is also of much higher quality, because of that.

I have tried finding alternative routes to get the good results out without having to just apply that much effort in my (unpaid) free time; the first option was LWN, which actually helped me paying for a good part of Yamato’s hardware. Unfortunately LWN is not a perfect solution for me; partly because my topics tend to be quite low-level, too low-level for the LWN readers I’m afraid, and too distant from the Kernel as well (which is probably the only low-level area that LWN really writes a lot about); the other problem is that LWN is still something similar to a magazine, a journal, and thus does not allow an easy way to organised documentation; like autotools-mythbuster is. It would still be a puzzle of entries; of higher quality than a blog, but still a puzzle.

The classical form for organised documentation is that of a book; in today’s age, ebooks are also quite often used, to avoid the whole mass-production and distribution trouble for topics that might not be of enough interest (interestingly enough, that’s not true still for a lot of books, so lately I actually had to by more paper books because I couldn’t find PDFs of them to use with the Reader). Now, this also have troubles; as you might remember I already tried looking for a publisher for Autotools Mythbuster, before going with the open project it’s now.

The idea behind that would have been putting as much effort as possible into that single piece of documentation, complete it as much as possible and get it out in some complete form. There you go: high-quality results, paid effort, and organised up. Unfortunately, finding a publisher is never an easy task, and for that topic in particular, I ended up hitting a stone wall: O’Reilly already had somebody working on the topic, and the book is out now I think (I haven’t read it). This actually was ignoring a problem with classical books: they cannot easily be updated; and documentation often has to be, to correct mistakes, grammar, style, and especially to be kept up to date with what they document. For instance, Autotools Mythbuster has a specific section on forward porting (which I’ll probably keep updating for the future versions as well).

So the final option was making it an open book; again, the effort is not ignorable, so my first solution was to write on it on a donation basis: would have covered the effort I needed to put into it, and would still have been able to be there for everybody. I didn’t count in the fact that the topic is too developer-oriented to actually be of any use to people who would be donating. Indeed, I wish to thank the last two donors (in terms of time), Thomas Egger (who sent me a good mouse to replace the stupid Mighty Mouse, you’ll soon see results about that, by the way), and Joseph Booker (who sent me some books, I started with The Brief Wondrous Life of Oscar Wao because I was meaning to read it for almost two years now, but the useful one will soon prove useful, I’m sure). But they, like most others, never explicitly named the guide. And so I’m trying to find more time for the general postings than that in particular.

Just a note before you start wondering about the guide; yes I haven’t updated it in a while. Why? Because I sincerely feel like it’s not useful any more. As I said it requires a positive amount of effort to be extended; there is, true, some interest on it, but not enough to actually have moved anyone to ever try funding its extension. With O’Reilly now publishing a complete book on the matter, I don’t think it’s worth my time keeping it up. I might still extend it if I have to correct some build system, or if I discover something new, but not going to keep extending it by my own will without such a need.

Bottom-line: I could probably write more extensive, organised, and precise documentation about lots of stuff, especially the stuff I write about on the blog from time to time, but the problem is always the same: it requires time and effort; and both are precious commodity; most of my time is already committed to paid work nowadays, and Gentoo is getting more and more to the third place (first is work, second health). Documenting what I can with the blog is, in my opinion, still better than nothing, so I’ll keep doing that.