By Victor Wheeler

1 Source-Code Documentation Best Practices

If you are a career software developer like I am, you are probably saying, “Here we are again talking about the age-old (sometimes controversial) topic of documenting source code.” Yet it is my hope that you will find this article unique and important in the industry because of the understandings it brings to tech writers, programmers, and executives who oversee software development teams (and are tempted to tell them not to spend time documenting source code).

This author’s aim is to address this particular audience and help bring about agreements that facilitate team coordination and cooperation as regarding documenting source code. My aim is to teach development teams faced with creating (and/or maintaining) source code that has a long life, especially when there will be many releases over its lifetime, and especially in collaborative development environments, that proper source-code documentation plays a huge role in the success of that software or library because if how it enhances that source code’s:

• understandability,

• extendibility,

• maintainability,

• correctness (see Articles on Documentation-Driven Development),

• reliability,

• ease of use,

• timeliness,

• repairability, and

• economy

throughout its lifetime.

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