Key Points

Introduction

  • Software documentation provides both users and developers information about what a software is supposed to do.
  • Software documentation has numerous benefits including improved team productivity, increased code quality, and better maintainability.
  • Software documentation can be challenging due to cost and time to maintain.

Types of Software Documentation

  • There are two primary categories for documentation: developer and user.
  • Developer documentation describes how developers should interface with a software package.
  • User documentation helps users be more successful in using a software package.
  • The Diátaxis framework reframes the categories — tutorials, how-to guides, reference, and explanation — and warns against mixing these modes.

Documentation Better Practices

  • It is important to be aware of potential unconscious biases when writing documentation. Make sure to consider culture, context, and experience.
  • No single practice will fit all software projects, but there are some generally better practices: version control, less is more, know your audience, document as you go.
  • GenAI can draft and gap-check documentation, but it lacks real project context — you supply the context and verify the output.

Documentation in Practice

  • There are numerous examples of different types of documentation in practice, each with its own intended purpose.
  • A project must pick the documentation that makes the most sense for its use case and domain.
  • The README is the front door; docstrings document the why; LICENSE and CITATION.cff make research software reusable and citable.
  • GenAI can draft documentation quickly, but you must review it for accuracy.

Documentation Tools

  • Documentation tools vary from style guides to IDEs to generators (Sphinx, Doxygen) to automated publishing.
  • Many tools have quick-start capabilities to get small or new projects started with better documentation processes.
  • Modern hosting (Read the Docs, GitHub Pages via Actions) rebuilds and publishes docs automatically — no manual branch management needed.
  • The same GitHub Pages tech can host a free personal website (YOURUSERNAME.github.io) from a template.
  • AI assistants can generate docstrings quickly, but always verify the output and mind data-sharing policies.