Followed by my previous blog post on Epistemology

Why people are reluctant to read TFM or TFA?

Let me give you an example. Google just announced Google Chart Tools, which looks fine to me, so the front page describes two kinds of charts: Image charts and Interactive charts, and blah blah blah pros and cons about choosing, and yet it links to their standalone blah blah page. Their separate page describes how to generate a chart, by adding epic long list of URL parameters.

So if you are about to use the Google Chart API, you have to read through their manuals, think about your goals, and interpreting them to a URL construction process, and viola your Chart is here.

But My questions is: do people really have to read a long and stupid post to make a chart?

Why can't we have a step-by-step, or a parameter tweaking GUI, like those we use in MS Office Excel?

The real stupidity lies in the difference of Procedural knowledge and Descriptive knowledge. Google Chart API manuals sucks, because the API authors translate a procedural HOWTO to a long and boring descriptive article, which I call it compiling. Now if a user wants to make a chart by Google Chart API, he has to translate it back to procedural practice, which takes a lot of time to decompile and shit load of extra effort to become proficient with this kind of work.

It's the same with FAQs. People seldom look into FAQs, but often ask more. Why? Because people are more willing to get to know how directly instead of know that. The future of FAQs, is to translate the Frequently Asked procedures into a formal semantic logical database, then a NLP frontend chat program to answer people's questions interactively.

However there's a useful aspect of the difference, if you want to make something deliberately hard to understand, you might want to translate it to descriptive form. From my personal experience, if Cisco books were too easy to understand and implement, the Internet would be more chaotic and messed up. Every netadmin and ISP would make some kind of modification and customization out of standard protocols, which eventually and ultimately makes the Internet un-inter-connectable.

tl;dr manuals, FAQs and long article sucks because the they fail to notice the huge difference between Procedural knowledge and Descriptive knowledge.