programming-for-dummies

286
Writing Software Documentation
Because most people don’t read user manuals,
many companies are resorting to video tutorials
that show movies of the program in action.
That way users can see exactly how to use
the program without having to search for that
information buried somewhere inside a thick
manual.
Unfortunately, video tutorials are limited. They
take time to create, so they usually cover only
the more common features of a program. If you
need help with a specific command, you need
Video tutorials
to first find the video file that contains the
answer and then you have to skim through the
video until you find your answer.
As a result, video tutorials act more as supplements
to the user manual than as replacements.
Video tutorials work best when they’re
kept short and focused on common tasks that
every user needs to know. After users get familiar
with a program with the help of video tutorials,
they’ll feel more confident using the help
files and reading the user manual.
Technical design
Programmers use a technical design document to organize how to write the
program. This means specifying how the program will work, what programming
language and compiler to use, how to divide the program into parts,
and assigning teams of programmers to work on each part.
Technical design documents usually start off being fairly complete and accurate,
but trying to design a program is much different than actually writing
that same program. Therefore, the design of a program can change as programmers
run into obstacles that they didn’t foresee ahead of time.
When this happens, the programmers often focus on solving the problem
and forget about updating the technical design documents, so the technical
design documents eventually become inaccurate and obsolete.
Programmers rarely want to update technical design documents because the
program may likely change again later anyway.
User manuals
User manuals are meant to teach people how to use the program. Ideally, a
program should be so intuitive that users don’t need a user manual. Because
that rarely happens, most programs include a user manual that explains how
to use every feature in a program.
Documentation tools
Unfortunately, most user manuals are notoriously inaccurate, confusing, and
incomplete: