Bad way to write documentation

This is from documentation for Boost.

Boost.Range is a collection of concepts and utilities that are particularly useful for specifying and implementing generic algorithms.

When documenting, it should be written to give a reader idea about what it is quickly and easily. Lengthy one is not necessarily bad though, if it’s required.

However, try to read the above sentence. What can you figure out from that? It’s nothing. It’s just like a vague marketing statement, which looks good on paper and especially when people just scan what is written. However, it’s just laying out useless words.

In 80’s and early 90’s technical books and writing written and published in US were largely good. They contain good snippet of code which can give you idea how things are expected to work one another.
However, nowadays, they tend to write 1~2 pageful sentences to describe very easy and straightforward concept. They just put one line of code, which doesn’t show how to use it related to other functions etc.
So, reading technical write-up nowadays is like reading novels rather than figuring out how to use interested techniques.

Probably it’s because everybody is a programmer nowadays? Everybody jumps onto mobile app market. Everybody says that they are S/W engineers. Wow…

I even bought a book ( which was unique in the market ) which was written by a lawyer.
I don’t know where it is after I tossed it to somewhere after reading one chapter.
It’s better to show full one sample code than explaining useless stuffs. Technical books on S/W programming should be written that, you are guided to write one sample program once they finishes explaining how to use this and that.

I didn’t buy any book on programming for the last 10 years, roughly speaking. It was better to grab official document from a company/open source project page, which is the origin of the interested frameworks/libraries and figure out for myself.

I doubt if S/W engineers actually write books nowadays. Probably some professional writers write ones for those S/W engineers who want to make side money or build some fame.


Leave a Reply

Please log in using one of these methods to post your comment: Logo

You are commenting using your 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: