This Time Self-Hosted
dark mode light mode Search

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.

Comments 7
  1. Well, IMHO you should switch your priorities #1 and #2. Unless you need the money for the treatment, that is, which I sincerely hope is not the case.Take care!

  2. Reason why work is over health right now is that health is mostly fine, and I’m in a particular situation where I need the money.

  3. One way to publish ebooks and get refund from them is to use services where you can sell also pdf/ebooks and get paid to download them. The lulu services let you easily update the docs and rise money at the same time.

  4. Mythbuster guide “table of contents” is not hyper-linked inside of each .xmli or at least; if I navigate to a page there is no way to go back to the index from within the doc.It seems quite useful to me for the stated intent. Documenting things some of the Gentoo developers should know.The topic is general enough however that it could also be said to extend the gnu documentation. Seems as though you should be eligible for funds from either of those projects. But that’s just my opinion.

  5. Disregard previous noise, found ‘up’ button.There is a publisher who has offices within a few blocks of my house. I could talk to these people on your behalf but would only do so if granted permission in writing. And only in the role of making them aware of how to contact you and said document. As you mention though the audience is rather limited and I have not seen the O’Reilly book at all. I have no experience in these matters.I can only surmise due to recent commits just sitting there that I have in some way contracted your ire with my high-handed American ways. If so I humbly apologize. I chose to use an old pseudonym so that I left no traces here that might be construed as leading to my own blog. Not that anyone who reads yours would have any interest in my blog anyway ;)My hope was to contribute in some small way to Gentoo and ‘free’ software. Frankly if those that profit by your work and the work of others who contribute to free software in general would submit some of those funds to developers such as you then you likely would not be posting this blog.Have you considered lecturing? ‘Ruby on Rails’ is certainly a timely topic that might generate some interest. As well as gnu autotools.Finally in my country you would likely be eligible for government grants…especially if you were a non-profit corporation and had a specific goal in mind.Sadly none of these is likely to help you meet any short term financial obligations.

  6. Hi flameeyes,I kinda know your problem: It’s far easier to write a Blog post than to write a structured document up front – and I think a major part of that is, that a weblog provides many more “Yes, I’ve done it!” moments than a book and has a much lower barrier to entry.I rather know it from the other side, though: I wrote a (german) roleplaying ruleset in a wiki, and I got very little feedback – even from the people I played with.My solution to that was to switch to Drupal which provides a book-style structure and a blog-style news section. I now write articles which can stand for themselves but which are automatically organized by section and keyword.I also do that for my personal page, but I think the RPG is a much better example (my personal pages are organized by content type/topic (song, poem, story, technical article, …), while the RPG sites articles are more connected):-> structure example for RPG:> blog style interface with description at the top:> blog style interface to all german stuff:…On the righthand side you see the book navigation. the equivalent on my main page about programs would for example be:->… “stuff about Mercurial”->… “blog style news”A similar structure should be useful for your documentation of programs. You can even first write an uncathegorized blog post and later sort it into its place (and also move it around freely afterwards) – for example when you realize that you write more about the topic.That way you can start with writing something about a new program, and give that program its own cathegory when you see that you’re writing about it more often.

  7. Hi Flameeyes,What is your opinion of a wiki-based book?-Solves the problem of time/resources by decentralizing the writing process.-Capable of high-quality book-like indexes, structures and style.-Allows for easy edits, fixes, and updates.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.