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
  • 6. Bibliography
  • View page source
Previous

6. Bibliography

6.1. Books

[Meyer1997]

Meyer, B. (1997). Object-oriented software construction. Prentice Hall. link

6.2. Articles on Test-Driven Development

  • Test Driven Development

  • A Guide to Test-Driven Development (TDD) with Real-World Examples

  • What is Test Driven Development (TDD)?

  • What is TDD?

6.3. Articles on Documentation-Driven Development

  • Why you should always do documentation before development

  • Getting Started With Documentation-Driven Development

  • Documentation driven development

  • Accelerate API dev with documentation-driven development

6.4. Articles on Sequence of Presentation

  • Old Information before New Information

  • Activating Prior Knowledge

  • Improving Cohesion

  • Acquiring New Information as a Process in Comprehension

Previous

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

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