avangate.com — Good documentation may exclude in many cases the need for further forms of technical support. It is, however, not easy to write. One of the reasons why this happens is that it is difficult for shareware authors or other software developers to put themselves into the users? shoes, since they are already thoroughly familiar with the application.
Aug 14, 2006 View in Crawl 4
4ndr01dAug 15, 2006
good design trumps reading the manual. if it's not intuitive it's crap!
saskaAug 15, 2006
"Horray for spelling nazi threads!"*milk exits nose*
akinderAug 15, 2006
Why the negatives? It was funny :P
imikedamanAug 15, 2006
Some people just can't take a joke. Plus the guy who said "your" was not correcting the first poster, he was going along with what he said.Quick at the keyboard; slow in the head.
kmedlinAug 15, 2006
This article did not seem to teach anything.It had a single paragraph providing only the most basic requirements for writing a manual. Nothing was said of style, ordering, or any number of other critically important elements. The article, while well meaning falls very short of being a high quality resource.For example, the article says, "Explanations are easier to understand if they are backed by pictures and diagrams, wherever possible." That's a great suggestion and one I see ignored all too often. The problem here is that it doesn't describe WHAT those pictures and diagrams should contain and what the frequency of "wherever possible" actually is!This tends to be a heated subject in writing manuals. Purists want more text than graphics arguing that well structured text that has been edited and reviewed will present a clear picture of the task without the need for dozens of images where only one or two may work.The other side of the coin, of course, is that no matter how great your text is and how well edited it may be, people will not read your narrative. They want to quickly look at the images, compare it to their screen, and perform basic actions while being guided along with both pictures and diagrams.Both sides have their merit, but neither truly addresses the main issue which is the manual revision cycle. This is a topic the article completely ignores and is where real manuals find their stride balancing topics that can be virtually ignored and expanding on topics in the manual that need further explanation. This article is interesting only in that it addresses a topic that is woefully overlooked by software publishers and particularly in the open source community where manuals, readme files, or other tutorial texts tend to be either out of date, inaccurate, or pure geek-speak.
coldchilliAug 15, 2006
This is for user documentation, not developer documentation.Good interface or training should solve most user issues. Try turning your code over to another developer to maintain without rewriting it. That takes talent
zedianAug 15, 2006
I think it was hit on the nail earlier than eve if you spend countless hours of laborious documentation writing, if you're users are lazy and don't bother to read it ---then it won't matter.Then again it wouldn't hurt to have documentation that is not so cut-and-dry and maybe even has a pink horse or cutesy little goldfish to entertain the brain of the user.::rollseye::
dualityAug 15, 2006
"good design trumps reading the manual.if it's not intuitive it's crap!"Tell that to everybody who uses vi on a regular basis.
adrianaiordanFeb 18, 2007
<a class="user" href="http://www.avangate.com/articles/Writing-Good-Software-Documentation_35.htm">http://www.avangate.com/articles/Writing-Good-Software-Documentation_35.htm</a>"How to write good software documentation", part 2.
supervapioApr 21, 2007
Sounds interesting... But I'm not surpised.
crossersJul 18, 2008
great! very useful thing! documentation writing is the general steps to your program!<a class="user" href="http://www.shpe-sac.org">http://www.shpe-sac.org</a><a class="user" href="http://www.ocflex.com/">http://www.ocflex.com/</a> <a class="user" href="http://www.trgovinca.org">http://www.trgovinca.org</a><a class="user" href="http://www.chasr.org/">http://www.chasr.org/</a>