Source-Code Documentation Best Practices

Contents:

  • 1. Introduction
    • 1.1. What Factors Give Quality to 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. 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.2. Learning Principle
      • 2.4.3. Sizes of Chapters, Sections and HTML Pages
      • 2.4.4. Summary
    • 2.5. Best Practices
      • 2.5.1. The Obstacles
      • 2.5.2. Strategy
        • 2.5.2.1. Definition of Strategy
        • 2.5.2.2. The Obstacles, Revisited
      • 2.5.3. Tactics
        • 2.5.3.1. Definition of Tactics
        • 2.5.3.2. Sequence of Steps to Produce that Documentation
  • 3. Software Documentation
    • 3.1. Learning From What Works
    • 3.2. Learning From What Doesn’t Work
  • 4. Source-Code Documentation
  • 5. Glossary
  • 6. Bibliography
    • 6.1. Books
    • 6.2. Articles on Test-Driven Development
    • 6.3. Articles on Documentation-Driven Development
    • 6.4. Articles on Sequence of Presentation
Source-Code Documentation Best Practices
  • Search

© Copyright 2024-2025, WGA Crystal Research, Inc..

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