Line By Line Review

LineByLineReview is a ProtoPattern for documentation.

Forces:

You want your documentation to be appropriate for specific audience(s).
Your TechnicalWriter(s) has (have) different backgrounds from one or more of the audience(s).
Your de facto TechnicalWriters may not be trained as TechnicalWriters. For example, they may be programmers, or users trying to make sense of a confusing system.
You are not sure if the documentation is appropriate for a specific audience.

Possible Solution:

Review documentation as thoroughly as PairProgrammers review code.

At a minimum: An intended user of the documentation reads through it carefully, in the environment where the documentation will be used, with the technical writer present (or nearby). A useful standard for "carefully": A careful reviewer will notice some of the spelling or grammar errors in the document. (Even after many reviews, there are usually some errors left.) A useful standard for "nearby": The observer notices when the reviewer is confused.

An extreme version: An intended user of the documentation pairs with another author during the writing of the documentation. For example, some projects' documentation is just collections of XP user story cards, typed up into a suitable permanent document. [AnswerMe: does anyone have specific examples of this?]

FaqAsDocumentation is another way to collect user stories and document them.

Even more extreme: Every story in the user manual must accurately describe a corresponding feature of the program. A third party should be able to walk in at any time, ask the user what they are doing, and be able to follow their process in the documentation. There should not be any discrepancy between the user manual, the program, and what the user actually does. This means that every story in the user manual is a demo, subject to being run at any time. Although demos are not automated (like AcceptanceTests), the result is similar. (This idea may be heavier than most ExtremeProgramming environments require.)

Resulting Context:

Often, this increases the length of the SignatureCycle, because the intended user is often not on the official SignatureCycle for the document.
Fortunately, the intended user is probably in the best position to notice errors, notice confusing details, or say "that misses the point".
More drafts fail at their early readings.
This shortens the SignatureCycle for failed drafts, and improves feedback.
The intended user feels part of the process. This can help them buy-in to the process.
To the extent that the reviewers are the users of the software, the software's users are better trained. (Because they have read the documentation, and because they get one-on-one answers to their questions.)
If the "even more extreme" idea is followed, the documentation is very accurate.
- It also adds inertia to the system -- new features must be documented, and new documentation must correspond to features.
- This strongly encourages consistency in the user interface. If a context-sensitive tweak to a feature requires doubling or tripling the documentation for that feature (in a confusing way), the context-sensitivity may not be worthwhile.
- It also encourages making the user interface genuinely self-explanatory, with fewer unnecessary steps.
- The documentation may need to be revised for every major iteration. (Minor iterations may get by with existing documentation, or with a temporary "red-line" of the documentation.)
- Shortening of the SignatureCycle is encouraged.
The intended user may not have time to perform such a detailed review, or may not feel comfortable pairing with the author. This brings up issues discussed in the PairProgramming and OnsiteCustomer pages.

Known uses:

NovaPlot at Hughes Electron Dynamics Division (EDD), which is now L-3 Electron Technologies. EDD makes TravellingWaveTubes and ion thrusters.

Related Pattern:

The ProgrammersGuiShorthand uses an arrow notation to document GUIs. This notation is brief enough to document a large project without people's eyes glazing over, but complete enough that the "More extreme version" of quality assurance is practical. It is also simple enough for the full range of users to be able to understand it.

Discussion:

MoreExtreme? is either an OxyMoron, or redundant.

The FaganDefectFreeProcess calls out a system for conducting inspections of code, documents, plans, requirements, specifications, magical incantations, and anything else that can possibly have defects. Fagan used data he collected over a 15 year period to fully flesh out this system and to back up his claims of being able to produce defect-free output.

Does the LineByLineReview ProtoPattern, with a good SignatureCycle, satisfy the requirements for a FaganInspection? (In a good SignatureCycle, each reviewer takes responsibility for those aspects of the change that are related to the reviewer's area(s) of expertise.) If the answer is no, what are the differences? If the answer is maybe, what clarifications are needed?

No. There are significant differences -- far too many to enumerate here. Please refer to FaganDefectFreeProcess for more detail. Also, Google is your friend.

[Related discussion moved to FaganInspection.]

See: DocumentationPatterns, SignatureCycle, ProgrammersGuiShorthand

CategoryDocumentation, CategoryPattern