Logo

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
  • Search

© Copyright 2024-2026 WGA Crystal Research, Inc. All rights reserved. Last updated on 27-Feb-2026.

Built with Sphinx using a theme provided by Read the Docs.