Why is software documentation so poorly written?
This is, if it can be found at all. I work on Microsoft systems. It can be very frustating at times to find out how to use their software. Microsoft’s site is typically not the best place to look. So one has to resort to using Google. What one frequently finds is incomplete and sometimes flat out wrong. Even when it can be found, it is typically given by way of an example that has what is desired buried in a sea of unrelated code.
You would think that a large company like Microsoft would be eager to have their software documented in a crystal clear fashion so that people could be productive and eager to buy their product. The explanation that people most often come up with is that the people in the best position to provide documentation, the developers, earn the company more money developing new software than documenting old software. I am not so sure that this is true. How much time should it take to write a simple explanation of how something should be done? How much money do customers lose trying to chase down the way to use Microsoft’s products?
Observing members:
0
Composing members:
0
19 Answers
Its not only the documentation, its their GUI as well, poorly designed, and cramming everything on the front page so to say…
They shoud do as apple did.. Hire experts to evaluate how people would like to use a piece of software, and adapt it to the customers, not adapt the customers to the product…
Now a developper with apples user friendliness and microsofts openess would be perfect for me :D
(Insert lame “I’m so glad I use a Mac” joke here)
=)
Same reason software is so poorly written. Remember the days before the Internet and you bought software in a box and it came with stacks of manuals? Now they can push out buggy software and just release patches. Same thing with documentation. Manuals are expensive to write and print. Fuck it, use Google.
The funny fact is that noone really codes software anymore… they mostly use ready made apps to make new software, resulting in memory leaks, increased size, more bugs, and such..
I remember I saw a fantasy landscape rendered in great 3D a few years beack… a virtual tour of the world around a castle with animations, etc…. it all tok 64kb… same thing now… my guesstimate is around halv a gigabyte atleast…..
There are exactly two people who can write software documentation:
1) The person who wrote the software itself. This person is not qualified to write documentation. He knows how to write code. He does not know how to write to people to explain the code.
2) A person who did not write the software, and is a dedicated documentation-writer. This person is not qualified to write the documentation, as he does not know the software as well as the person who wrote it, and in fact only knows what the software writer can tell him.
Companies often make the assumption that if you graduated from college, you can write a user manual, and look at professional writing as a way trim costs. Same goes with proofreading; how many companies have professional proofreaders these days?
The intersection of people who love computer languages and people who love natural languages like English is almost empty.
If the documentation is obscure, that creates a market for secondary consulting and for customer support with a per-incident fees.
Microsoft can pay people $50 to $75 an hour to write clear documentation, or they can bill people $100 to $200 an hour to explain the software to them. Which one do you think they prefer?
Because nobody reads it. Seriously. After a while, you get to know what features of a computer or program that people use the most, and you can answer questions about them, or write up summaries. But in order to fully document something like Excel, you’d wind up with thousands of pages that nobody would ever bother looking through to figure out how to do something simple, like change the row height.
@cwilbur, the best-kept secret at Microsoft is the public newsgroups. You can get a better answer there than you’ll ever get from their paid support, and you’ll get it for free. Try it sometime, you will be amazed. You can get to them from Microsoft’s site, but you can also ask a question there with any Usenet news reader.
@IchtheosaurusRex: given that I don’t use Microsoft products, I doubt that their public newsgroups would be much use to me.
@cwilbur , if you don’t use them, don’t criticize them. It makes you sound officious.
@IchtheosaurusRex: When they stop producing crap, I’ll stop criticizing them, and I might start using them.
@IchtheosaurusRex: Cwilber didn’t sound officious to me; he didn’t even sound sententious. He was reporting a fact. However, in most recent answer, he did render an opinion.
I don’t ride a motorcycle so I have no use for Harley forums. Statement and not opinion.
@gailcalled Well, excuuuuuuuuse me. This quip is opinionated – hostile, in fact; it is unsupported by any citation, and offers no counterexamples. His response to my post was non sequitur and contributes nothing to the discussion. I know you guys are a bunch of Macheads over here, but that was pretty well over the top.
@IchtheosaurusRex: I thought you were referring to the answer just above yours; viz;
”@IchtheosaurusRex: When they stop producing crap, I’ll stop criticizing them, and I might start using them.”
I still think that the quip you were referring to was not officious. There were similar opinions rendered.
Well, I just don’t like to see them unfairly maligned. Maligned yes – I’m the first one to stand up and shout “Vista sucks ass” – but to accuse Microsoft of intentionally obfuscating their documentation in order to drive people to expensive tech support is just short of libel.
In point of fact, Microsoft documentation is pretty good, if you know how to search for it. There’s the rub. You can spend hours fruitlessly searching for answers to a simple question like “how do I make my menus stop fading out.” This is because of the points I raised in my first answer; Microsoft as well as other software vendors tend to weight all information equally, and there is way too much information.
@Icthy: How can I feel anything but benevolence for the user of “officious, “non-sequitor,” “obfuscating” and “maligned”? (And one who knows the difference between “weigh” and “way” is my friend for life.)
Discloser; I own a Mac
@gailcalled – nuthin’ but Lurve for ya.
I would own a Mac, too, if I needed another hobby. But they pay me to write Windows code and a man’s gotta eat
Answer this question 
This question is in the General Section. Responses must be helpful and on-topic.
Composing members:
0
