ifacethoughts

It Does Not Work As Documented

While many of you might consider this bad and unprofessional, I think importance of documentation can vary by project. Linus Torvalds recently said about Linux kernel:

Rule #1 in kernel programming: don’t *ever* think that things actually work the way they are documented to work. The documentation is a starting point, nothing else.

I think this can be said about a lot of system software. There is a school of thought on user documentation that says the software design should usable and intuitive enough to guide the user by itself, without user documentation, which I do not fully agree with. I acknowledge that the RTFM attitude is bad, but help should be handy as well, especially if your user base has a wide profile range.

A lot of programmers feel that comments are not necessary, but I find a place for them in explaining the problem the code is trying to solve. Another place where documentation can be useful is to record rationale of various decisions taken.

I agree with what the quote says, especially in the programmer documentation. The documentation can work well in the beginning, but cannot keep up with the changes and evolution. However, in most of the cases I feel documentation is important to indicate what it is doing rather than how something works.

Say your thought!

Who are you?

If you want to use HTML you can use these tags: <a>, <em>, <strong>, <abbr>, <code>, <blockquote>. Closing the tags will be appreciated as this site uses valid XHTML.

This is the weblog of Abhijit Nadgouda where he writes down his thoughts on software development and related topics. You are invited to subscribe to the feed to stay updated or check out more subscription options. Or you can choose to browse by one of the topics.