Contents:
1. Introduction
1.1. High Quality in Source Code
1.1.1. External vs Internal Quality Factors
1.1.2. External Quality Factors
1.1.2.1. Competing Quality Factors
1.1.2.2. Key External Qualities
1.1.3. Internal Quality Factors
1.1.4. The Omitted-but-Super-Important Quality Factor
1.1.4.1. Reason
1.1.5. Summary
2. Documentation Best Practices
2.1. Purpose
2.2. Governing Principle
2.3. What Is Documentation?
2.4. Qualities of Good Documentation
2.4.1. Obvious Qualities
2.4.2. Not-So-Obvious Qualities
2.4.2.1. The Case for Sequence of Presentation
2.4.2.1.1. Raising the Reader’s Awareness—Orientation
2.4.2.1.2. Raising the Reader’s Awareness—Understandings
2.4.2.1.3. Raising the Reader’s Awareness—Enlightenment
2.4.2.1.4. Layers
2.4.2.2. Learning Principle
2.4.3. Summary
2.5. Best Practices
2.5.1. Obstacles
2.5.2. Strategy
2.5.2.1. Definition of Strategy
2.5.2.1.1. What Does Strategy Do?
2.5.2.2. The Obstacles, Revisited
2.5.2.2.1. Strategy #1A: Make it Easy to Find and Easy to Access
2.5.2.2.2. Strategy #1B: Reduce Time Required to Achieve Initial Success with Your Product
2.5.2.2.3. Strategy #2: Make Topics Easy and Quick to Find
2.5.3. Tactics
2.5.3.1. Definition of Tactics
2.5.3.2. Tactics to Produce that Documentation
2.5.3.2.1. Create a Plan
2.5.3.2.2. Work From that Plan
2.5.3.2.3. Use Only Terms the Reader Knows or Can Easily Look Up
2.5.3.2.4. Ensure the Reference Section is Complete First
2.5.3.2.5. Write the Orientation Material
2.5.3.3. When to Move Subtopics to Separate HTML Pages
2.5.3.3.1. When Moving Subtopics into Separate HTML Pages Can Be a Problem
2.5.3.3.2. Additional References Favoring Longer Pages with Subsection Structure
2.5.3.3.3. Arguments in Favor of Shorter Pages
3. Software Documentation
3.1. Learning From What Works
3.2. Learning From What Doesn’t Work
4. Source-Code Documentation
4.1. The Problem Being Solved
4.2. An Alternate View of the Problem
4.3. The Solution
4.3.1. What is Internal Documentation?
4.3.2. Factors
4.3.3. Measurement
4.3.4. The Basic Questions—Revisited
4.4. Additional Reading
5. Donald Knuth on Literate Programming
6. Bertrand Meyer on Terseness in Code Documentation
6.1. Chapter 26: A sense of style
6.1.1. COSMETICS MATTERS!
6.1.1.1. Applying the rules in practice
6.1.1.2. Terseness and explicitness
6.1.2. HEADER COMMENTS AND INDEXING CLAUSES
6.1.2.1. Routine header comments: an exercise in corporate downsizing
6.1.2.2. Indexing clauses [module orientation for programmers]
7. Glossary
8. Bibliography
8.1. Books
8.2. Articles on Test-Driven Development
8.3. Articles on Documentation-Driven Development
8.4. Articles on Sequence of Presentation
8.5. Articles on Consequences of Poor Code Documentation
Source-Code Documentation Best Practices
Index
Index
A
|
C
|
D
|
E
|
F
|
I
|
M
|
O
|
P
|
R
|
T
|
U
|
V
A
astutely
C
compatibility
context
correctness
D
documentation
E
ease of use
economy
efficiency
extendibility
F
functionality
I
integrity
M
maintainability
maintenance
modularity
O
orient
orientation
P
portability
problem domain
R
readability
reliability
repairability
reusability
robustness
T
testability
timeliness
U
understandability
understandable
understanding
V
verifiability