digg

Join DiggAbout

Discover the best of the web!
Learn more about Digg by taking the tour.

Learn how to write good documentation for your software

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.

Bury
show profanity settings
expand all
  • i440, on 10/12/2007, -19/+24Also, always remember the Three Most Important Truths for Writing Documentation:

    1.) Always always write in technical language people new to computers can never understand.
    2.) Always assume people know all the basics to your software.
    3.) If you're tired, just put a FIXME there and don't even bother continuing to write it's all good
    • RidinDirty, on 10/12/2007, -0/+5HAHA! ...types "grep -r FIXME *" Hmmm.. more than a screenful of data. I'm on the right track.
    • akinder, on 10/12/2007, -0/+5Why the negatives? It was funny :P
    • sirber, on 10/12/2007, -1/+5too long.

      write no doc, easier :D
  • scottmoss, on 10/12/2007, -18/+6Wong! always stert width spealling!
  • tizz66, on 10/12/2007, -0/+9Good advice. As a technical writer, I wouldn't advise going for pure 'how to' documentation over command-by-command. Both is best. Not everyone knows exactly what they want to achieve - some may want to know what a particular function does or what a a part of the system supports etc. Limiting yourself to a Q&A-type format makes it more difficult.
    • Haplo, on 10/12/2007, -0/+1command by command should be in an appendix IMNSHO and the majority should focus on how to. Most documentation is just a left to right, top down explanation of each menu entry, which fails on both accounts.
  • Pile, on 10/12/2007, -3/+17Step One: become literate. 90% of the net populace aren't ready for Step Two yet.

    Learn the difference between "you're" and "your."

    Punctuation is your friend. Understand what a semicolon is.

    Basic *****.. like starting a sentence off with a Capital letter and ending with appropriate punctuation.
    • TechScribe, on 10/12/2007, -0/+3Guess I'll always have a job!
    • celopes, on 10/12/2007, -1/+2... and the difference between it's and its.
      ... and the amazing function of a spell checker.

      And that, my friends, is just the tip of the iceberg for English speakers. If we start dealing with translations... wow...
  • ventraldogma, on 10/12/2007, -1/+4Good stuff. Only problem is, no matter how good the documentation it won't help with lazy users.
    • whiskeymb, on 10/12/2007, -0/+10totally agree... I've written a few documents for our products and spent many many many hours doing so and it kills me everytime I'm on the phone with one of them and I say "did you read the guide I sent you" ... "no...."... well your answer is on page 19.

      no amount of good documentation will make up for the fact that most people don't read them.

      also, a handy "cheat sheet" for the most common tasks is VITAL!
    • merreborn, on 10/12/2007, -0/+1"Good stuff. Only problem is, no matter how good the documentation it won't help with lazy users."

      Not really true: It's a hell of a lot easier to say "Read the documenation provided here" in response to a support query, than it is to write out the same response every time someone asks the same stupid question.

      True, you can't make your users read documentation before contacting you, but you can still use it as a reference when they do finally reach you.
    • celopes, on 10/12/2007, -0/+1Ding! Ding! Ding!

      And that is why investing in usability is so important. Highly evident user interfaces will lessen the burden on support people. A wise investiment any day of the week.
    • kmedlin, on 10/12/2007, -0/+0Then adapt to newer forms of tutorial assistance. Not to promote any particular product, but we've had great success with Camtasia Studio. Robodemo and a few others out there are equally good at providing easy to create, high quality, streaming video tutorials!

      We've had fantastic traction amongst users and even get suggestions from them on topics they'd like to see next. So it's truly a collaborative documentation process where the end users are feeling engaged.
  • plqplq, on 10/12/2007, -1/+2Yep, you need how-to, reference, and probably "getting started"

    One point they missed was that with modern tools (or a bit of programming) you can combine the online help with the manuals, so you only have to write the content once !!
  • evilTak, on 10/12/2007, -1/+4"Shareware authors" ? Was this written in 1986?
    Including the ship date in the readme?

    The author seems a little out of touch...
  • dAbReAkA, on 10/12/2007, -0/+5i would say "Learn how to write good software" first.. we're surrounded by bloat software, let alone documentation..
  • threeandout, on 10/12/2007, -0/+0# this function returns the calculation from the function that you wrote yesterday
  • 4NDr01D, on 10/12/2007, -2/+5good design trumps reading the manual.

    if it's not intuitive it's crap!
    • Nightspark, on 10/12/2007, -0/+2I agree that software should be well designed, but something non-intuitive isn't always crap. New functionality that your users aren't familiar with might not be intuitive for them, and large powerful applications probably can't have everything in them be intuitive.

      Additionally, what seems intuitive to one user doesn't always seem intuitive to another user. So while good design is very important, good documentation is also very important.
    • duality, on 10/12/2007, -0/+1"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.
  • haggie, on 10/12/2007, -3/+1"write good"?

    Looks like taking a remedial English class is the best bet for improving your software documentation.

    • Moskie, on 10/12/2007, -1/+4Ah, yes, it should be "Learn how to write well documentation for your software."

      Your a genius.
    • robdavy, on 10/12/2007, -3/+2*you're

      ;-)
    • shadedream, on 10/12/2007, -1/+2"You're" a genius too!

      Horray for spelling nazi threads!

      [edit] aww beat me to it... LOL I find it amusing how about everyone that corrects people's spelling in these threads cant get down basic usage of you're/your
    • saska, on 10/12/2007, -0/+2"Horray for spelling nazi threads!"

      *milk exits nose*
    • reikun, on 10/12/2007, -2/+0umm.. actually i think the original headline is correct.

      This is because "good" isn't describing "write" but "documentation" instead. Thus, by property of being an adjective "good" does not change to 'well' since 'well' is an adverb.

      if that doesn't make sense, then consider:

      I write well.
      I write good stories.
      I code well.
      I code good websites.

      uh. yeah thats it.
    • imikedaman, on 10/12/2007, -0/+2Some 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.
    • Moskie, on 10/12/2007, -0/+2My reply was meant to be sarcastic. Anyone who can't tell that the headline is correct ("good" is right, "well" would be wrong) really does need a remedial English class. The "your" typo was (intentionally) thrown in for good measure.
    • reikun, on 10/12/2007, -0/+0My comment was strictly "for informational purposes" only. I just find it annoying to have to scroll through a long menagerie of comments to find half of them, should I say, "obsolete."

      ~meh. who am i kidding? go ahead post what ever you like. because i too love my 1st Amendment rights.
  • justice7, on 10/12/2007, -1/+1learn how to write good documentation?

    i think its called go get some post-secondary education in the field and watch your professor mark RED LINES all over your page until you know how to document properly

    doesn't matter how pretty your code is, if its not documented properly.. your professor probably won't accept it.
  • haggie, on 10/12/2007, -0/+0Learn how to write well when documenting software.
  • saska, on 10/12/2007, -0/+4Tech writing is my field, and the longer I spend in it, the more I hate freeware. When I go to the Help and it says "I wrote this in the spring of 1999 for my CompSci BS final," I want to reach through my computer and kill, kill, kill.

    Document what people need to know. Don't ramble on and on about the theory behind your application. Nobody except you cares. Ask yourself what people can do with your application and then write procedures for how to do each of those tasks, organized in an easy-to-navigate table of contents. Don't bury common tasks under four headings. Keep them all at a flat level where a user can find them at a glance.

    When you document command line utilities, document the command syntax, and then the flags, and then give examples. Do not mix up the order. Do not list some examples and then some more flag definitions. Just don't.

    But above all else:

    WRITE YOUR DAMNED USER INTERFACE SO IT DOES NOT NEED A HELP FILE. Then everybody wins.
  • spyrochaete, on 10/12/2007, -0/+2Documentation doesn't have to be in a printed manual. Online contextual documentation is an invaluable resource. Nobody likes looking through manuals. Having procedures and help suggested to you is where it's at.

    For instance, I've always found Windows XP's explorer brilliant. You open an explorer window and you are immediately given a list of commonly used options to consider. You click a folder and you're shown folder-specific options. Click a file and you're given different options. Very smart.
  • imikedaman, on 10/12/2007, -0/+2The secondary reason why most developers can't write good documentation is because programming is a very left-brain function (math and logic), while creative writing is a very right-brain function. Some developers are very good at writing documentation for their own software because they have both technical abilities and excellent writing abilities.
  • aychamo, on 10/12/2007, -0/+0This article is crap. It's hardly a few paragraphs. How can people not be embarassed to publish this garbage? "Oh wow.. Put my name in a readme file? Great advice, thx!"
  • duckslut, on 10/12/2007, -0/+0edit@aychamo: Hell yea.

    I don't know why this person felt the need to write this article.

    It's not like he's bringing a problem to attention that no one knew about or contributing anything meaningful to the solution.

    If I wrote only the documentation he suggested that would be some ***** documentation.
  • kmedlin, on 10/12/2007, -0/+0This 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.

  • RickG, on 10/12/2007, -0/+0The best way to write good documentation is the write it before writing any code. Then keep rewriting until you get sign off from you client/customer/boss/whomever. This is the best time saving advice I ever received.

    Once you've got sign off there is no mistaken what was wanted. No need to rewrite sections. And once the coding is done there isn't the arduous task of writing documentation; it's already done.
  • ColdChilli, on 10/12/2007, -0/+1This 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
  • Stopher, on 10/12/2007, -0/+1What's documentation?
  • shaneb06878, on 10/12/2007, -0/+1i++; // increment i by 1
  • Zedian, on 10/12/2007, -0/+0I 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::
  • mkrigsman, on 10/12/2007, -0/+0Go to http://www.documentation.com
  • adrianaiordan, on 10/12/2007, -0/+0http://www.avangate.com/articles/Writing-Good-Software-Documentation_35.htm
    "How to write good software documentation", part 2.
  • supervapio, on 10/12/2007, -0/+0Sounds interesting... But I'm not surpised.
  • crossers, on 07/18/2008, -0/+0great! very useful thing! documentation writing is the general steps to your program!
    http://www.shpe-sac.org
    http://www.ocflex.com/
    http://www.trgovinca.org
    http://www.chasr.org/
  •  

    Login or register to add a comment

    Create a new account or login to join in the conversation on Digg. You'll also be able to Digg stories to help promote things you like.


© Digg Inc. 2008 — Content posted by Digg users is dedicated to the public domain.
DIGG, DIGG IT, DUGG, DIGG THIS, Digg graphics, logos, designs, page headers, button icons, scripts, and other service names are the trademarks of Digg Inc.