topbanner_forum
  *

avatar image

Welcome, Guest. Please login or register.
Did you miss your activation email?

Login with username, password and session length
  • April 25, 2018, 07:24 PM
  • Proudly celebrating 13 years online.
  • Donate now to become a lifetime supporting member of the site and get a non-expiring license key for all of our programs.
  • donate

Author Topic: Writing Good Software Documentation  (Read 4321 times)

Wordzilla

  • Forum Search Daemon
  • Charter Member
  • Joined in 2005
  • ***
  • Posts: 470
  • Two there should be; no more, no less.
    • View Profile
    • FreeThesaurus.net - The Free Online Synonym Finder
    • Read more about this member.
    • Donate to Member
Writing Good Software Documentation
« on: November 24, 2006, 12:13 AM »
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.

Screenshot - 24_11_2006 , 5_10_05 PM.jpg

mouser

  • First Author
  • Administrator
  • Joined in 2005
  • *****
  • Posts: 38,436
    • View Profile
    • Mouser's Software Zone on DonationCoder.com
    • Read more about this member.
    • Donate to Member
Re: Writing Good Software Documentation
« Reply #1 on: November 24, 2006, 03:01 AM »
nice find.  :up:

brownstudy

  • Honorary Member
  • Joined in 2006
  • **
  • Posts: 28
  • Pantaloon
    • View Profile
    • Oddments of High Unimportance
    • Donate to Member
Re: Writing Good Software Documentation
« Reply #2 on: December 09, 2006, 10:21 PM »
I've been tech writing for umpty-ump years. My two tips for newbies:

1. The web has taught people to scan, not read. Write in short squibs, keep the humor to a minimum unless you're really funny, keep it scannable. Save the long text passages for the advanced topic where the interested user will be expected to invest their time to learn the good stuff.

2. If you find yourself dumping every scrap of info you have into the documentation, then you haven't decided who the audience is, what they'll use the info for, or you don't understand the product. Figure out which one is the real problem. Your job as the writer is to select and contextualize the information so it goes down like chocolate milk, or at least doesn't cause cognitive pain. It's not the user's job to sift through the documentaiton to find the good stuff, it's your job.

I have some delicious links on tech writing here: http://delicious.com...ownstudy/techwriting

A really really interesting longish read is this essay on adapting Agile strategies for writing agile documentation:  http://www.agilemodeling.com/essays/agileDocumentation.htm
« Last Edit: October 27, 2014, 04:55 PM by mouser »

tinjaw

  • Supporting Member
  • Joined in 2006
  • **
  • Posts: 1,927
    • View Profile
    • Donate to Member
Re: Writing Good Software Documentation
« Reply #3 on: December 10, 2006, 09:41 AM »
brownstudy,

That is some excellent advice. And not just for n00bs either.  ;)
http://www.donationcoder.com/forum/index.php?topic=6263.0
www.donationcoder.com
crawl=CC-MAIN-2018-17
59743
application/http; msgtype=response
sha1:5WYF3IYE5FFGL2I5SZYUC4OQQXCNU6F2
<urn:uuid:dfa92858-42c7-4ed0-968c-a080af938f60>
2018-04-26T00:24:20Z
74.50.117.94
text/html
sha1:PAIHV6WWLSCBRCXCTSINKOOZ7NO5SMJE
<urn:uuid:6e51f3c3-3be4-4553-8fb9-1f44b8a4d77c>
http://www.donationcoder.com/forum/index.php?topic=6263.0
length
response
<urn:uuid:2e6c2c12-04c5-4d5a-887a-16d4d8b5d778>
robots: classic
hostname: ip-10-185-176-92.ec2.internal
software: Nutch 1.6 (CC)
isPartOf: CC-MAIN-2018-17
operator: Common Crawl Admin
description: Wide crawl of the web for April 2018
publisher: Common Crawl
format: WARC File Format 1.0
conformsTo: http://bibnum.bnf.fr/WARC/WARC_ISO_28500_version1_latestdraft.pdf