Problems with Current Technical Manuals
As a “hands-on” person, I have to learn new tasks frequently because technology is constantly changing and my position demands frequent knowledge refresh. I suppose that I am qualified to identify this problem and ask the question, “Why is it so hard to understand technical manuals written by software vendors?” When learning a new technology, majority of us, “tech guys”, would rather just look for a blog and follow “some other guy’s” explanation and step-by-step approach rather than read the documentation written by the software vendors. Why?
Is it me or is it the writers?
I used to think that this was my problem. I used to think that I was just not technical enough and that was why I could not just follow the documentation to understand and use new technologies. However, after spending almost two decades in the industry and training many other people, I am convinced that this is certainly not just a “me” problem. Sometimes, I still have to search for online blogs to understand new technologies even when vendor documentation for these technologies exist. Do the technical writers know that even highly technical people still have problems understanding and using these documentations?
Suppose I am wrong. What about the Others?
So let’s suppose that I am wrong about my conclusion that many vendor software documentations are currently not effectively serving their targeted audiences, what about all the questions on all those technical blogs on the internet? If the documentation were easy to understand, why are there so many blogs re-writing the documentations in comprehensible manner? Why do the blogs get thumbs-up from all their supposedly “technical” followers? If I am wrong about my conclusion, would you please answers these questions?
Why Current Technical Manuals are bad
Going by the outcome of events as listed above, technical people prefer to read manuals written by other technical people that are trying to accomplish the same task. Conversely, we can say that current technical manuals are horrible because they are mostly written by professional technical writers who, by virtue of their trade, do not think or solve problems like technical people and, as such, are bad presenters of information to technical people. This is not an attempt to discredit the role of technical writers but to help them focus on the appropriate audience: non-technical people. Professional technical writers should make documentation for people who have little or no technical background.
The Other Important Component of Good Technical Manuals
Independent blogs make better technical manuals because they are mostly written by people who have genuine interest in technology and an apt for explaining how things work. Technical manuals written by highly technical engineers who are working on the subject software are less likely to be effective because the engineers will generally make incorrect audience knowledge assumptions. Therefore, bloggers are the best people to write technical manuals for emerging technologies and I think that software vendors should contract bloggers for the purpose of software documentation. This approach will be cheaper and will serve the audience better than creating software documentation in-house.