Follow Slashdot blog updates by subscribing to our blog RSS feed


Forgot your password?

Slashdot videos: Now with more Slashdot!

  • View

  • Discuss

  • Share

We've improved Slashdot's video section; now you can view our video interviews, product close-ups and site visits with all the usual Slashdot options to comment, share, etc. No more walled garden! It's a work in progress -- we hope you'll check it out (Learn more about the recent updates).


Writing Documentation: Teach, Don't Tell 211

Posted by Soulskill
from the here-is-a-screen-full-of-words,-go-wild dept.
Programmer Steve Losh has written a lengthy explanation of what separates good documentation from bad, and how to go about planning and writing documentation that will actually help people. His overarching point is that documentation should be used to teach, not to dump excessive amounts of unstructured information onto a user. Losh takes many of the common documentation tropes — "read the source," "look at the tests," "read the docstrings" — and makes analogies with learning everyday skills to show how silly they can be. "This is your driving teacher, Ms. Smith. ... If you have any questions about a part of the car while you’re driving, you can ask her and she’ll tell you all about that piece. Here are the keys, good luck!" He has a similar opinion of API strings: "API documentation is like the user’s manual of a car. When something goes wrong and you need to replace a tire it’s a godsend. But if you’re learning to drive it’s not going to help you because people don’t learn by reading alphabetized lists of disconnected information." Losh's advice for wikis is simple and straightforward: "They are bad and terrible. Do not use them."
This discussion has been archived. No new comments can be posted.

Writing Documentation: Teach, Don't Tell

Comments Filter:
  • by LinuxIsGarbage (1658307) on Tuesday September 03, 2013 @08:54PM (#44752375)

    And for no arguments. Or at least print what is required to get help

    Crappy app
    GPL 2 (If you don't like it fix it yourself

    For help type -?

    C:\>app /?
    Crappy app
    GPL 2 (If you don't like it fix it yourself

    I said enter -?, not /? This program was barely ported using cygwin, so you have to use *NIX arguments
    Don't like it, fix it yourself

  • by youngatheart (1922394) on Tuesday September 03, 2013 @09:24PM (#44752561)

    Oh cool! I known that shutdown -r -t 600 works on Windows when I expect it to finish installing an update and I'm ready to go for a coffee, but I never remember what it is in Linux. Thanks to your tip, I now know I can use shutdown -h but I know the Linux guy had to put a number, so let me try shutdown -h 0 and see what it tells me about how

  • by VortexCortex (1117377) <`VortexCortex' ` ...'> on Tuesday September 03, 2013 @09:44PM (#44752675)

    -h? Next time, use all three of these: -?, -help, --help. I'm probably not going to try throwing -h at a program without having a clue what it might do.

    Then use the damn manual. That's why we write them. If you want to know how to use the manual, use the manual:
    $ man man

    ... hmm, That gives me an idea.
    $ man woman
    No manual entry for woman

    Yep. It knows everything!

  • by noh8rz10 (2716597) on Wednesday September 04, 2013 @12:07AM (#44753371)

    reminds me, I hate man pages. there, I said it. they are the devil. i have never learned anything important from a man. rftm, you say? well stfu!

Sigmund Freud is alleged to have said that in the last analysis the entire field of psychology may reduce to biological electrochemistry.