jump to navigation

is Documentation skill a requirement? (2) February 12, 2007

Posted by TSAI HONG-BIN in Programming.

Writing documentation is somewhat like telling a story. You have to focus on the 6-Wh, What, Why, How, Who, Where, When. Maybe more emphasis on What, Why and How, but if possible, it would be great to answer all the 6 questions.

There are certain levels of documentations. 1) commented inline with source code, explaining variables, parameters, functions…etc. 2) noted in a seperate file, explaining the program from a “higher” aspect of view such as the co-relationship between classes, objects, members. 3) written down as an independent document or usually called “white paper,” which explains what problem this program means to solve, what algorithm this program applies, what’s the expectation of this program in the future…etc. Each level of documentation has different purpose and focus, and last but not least, different target audience.

Since in my last post I mentioned that software engineers are more or less linguists, this line is definitely not joking those who are able to write excellent programs but have no idea how to have a casual talk with gals. One who wants to write a program, must learn its programming language first. But by knowing languages and grammers may only allow you to write a homework. If you want to implement something cleverly, you have to “understand” the language. It’s undoubtedly a challenge, especially when it is a machine that you want to communicate with via the programming language. The syntax must be accurate, logical must be correct, and even there are times you have to deal with memory management. Assume that now you’re able to write masterwork, there’s still one step to go. Yes, documentation. By writing documentation, you’re no longer talking to machine (compiler, to be exactly), but to human readers.

Why is documentation a necessary step? I believe one of the most important feature is to let your program “live long and prosper.” You may hear from your C language lecturer that a source code cannot be reused is useless. Though usually this guideline is employed to urge you to “modulize” your program, it is somehow applicable to the case that a million-line source code contains no documentation.

(to be continue)



No comments yet — be the first.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: