Line By Line Review

LineByLineReview is a ProtoPattern for documentation.


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:

Known uses:

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

Related Pattern:

  1. 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.


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

View edit of May 12, 2011 or FindPage with title or text search