7.14. Proofreading

Check the spelling, syntax, and sanity of your documentation.

The point of all documentation is communication: either with the users of your code, or with those who maintain it. To be effective, documentation must communicate effectively. It must be without distractions (like spelling mistakes), it must be comprehensible (i.e., syntactically correct), it must be unambiguous, and it must make sense.

So, although it's important to write your documentation, it's far more important to read it after it's written, to make sure it will do the job you created it to do.

The best way to proofread a document is to look at a "rendered" version of it. That is, don't simply reread the POD source you just wrote. Instead, convert that POD to plain text (using perldoc) or to HTML (via pod2html) or even to LaTeX (with pod2latex), and then read through it using the appropriate display tool.

Better still, have someone who's unfamiliar with the code read through your documentation. A new reader will be far better able to recognize when some part of your explanation is confusing, ambiguous, or otherwise unenlightening.