Documentation content and organization

How to organise content

  • Documentation should be near the code (or in the code),

    • Same repository or project space

    • Documentation should be version controlled tied with software releases

    • For user-facing documentation, start with a well-structured README

  • Topics should be organised in logical, maintainable groups in directory structure

Content accessibility and findability

  • Consider who is using your tool/service and what they want to find

  • Documentation should include clear and logical navigation from various topics to related topics.

  • For medium to large projects: a dedicated documentation platform should be considered (e.g., Read the Docs)

  • Consider that every page is page one (a user can land on any page as a starting point and need to find their way to their desired goal)

  • Types of navigation you can include:

    • Table of contents (global across website and local to the page)

    • Breadcrumb trail

    • previous / next buttons

    • ‘see also’ sections

    • appropriate links within text

  • Include a search bar

  • Descriptive titles and headings (not Introduction but How to do X)

  • Up-to-date links to other relevant pages

Types of documentation content

  • Technical/ Developer documentation

    • High level documentation

      • Understand the overall architecture/design (how is the tool/service built and why),

      • Set objectives (what is the aim of the project, what problems are trying to be solved),

      • Implement workflows (how is the tool/service AND the documentation built, maintained and deployed, what is expected of developers)

    • Low level documentation (Code comments, docstrings etc)

      • Explain what the code does,

      • why code is the way it is, and

      • how it relates to other parts of the code

    • Release notes to track relevant changes

  • User facing documentation

    • Explicit installation instructions including prerequisites

    • A good explanation to what the tool/service is or does and who its for

    • Useful example(s) of how its used

    • Deep dives into specific topics: Guides, how-tos, and tutorials

    • API docs

    • Glossary

    • troubleshooting/FAQs

    • Contact info to ask questions and learn how to contribute

    • Link to relevant peer-reviewed publication(s) (if relevant)

    • Citation info for this software / service

    • License info

    • Acknowledgments (funders, institutions, etc)

Content development

  • Encourage community involvement (create issues, provide feedback, contribute directly to documentation etc)

  • Ensure the documentation you’re creating is useful to your user base. (Consider the value to the audience if adding new features / content).

  • Use subject matter experts (SMEs) to develop content alongside developers

  • Use a to help develop consistent documentation

  • Ensure documentation is understandable by the main audience (consider non-native speakers)

  • Ensure documentation is skimmable and varies in text type (bullet lists, paragraphs, tables) and visuals (images, gifs, code blocks, graphs etc)

  • Never assume your audience knows what you know

  • Use templates or examples for contributors. This makes it easier to contribute content. And the content retains consistent structure.

What should be in a style guide?

  • There are a ton of existing style guides for software documentation - use them as resources and references

  • See also this template Styleguide for your docs

  • Keep it light-weight (use other resources as links for further details)

  • The goal of style guide is to provide a single reference point for content creation. This helps ensure the documentation remains clear and consistent.

  • Focus on important concepts that contributors need to know (what kind of formats/language do you use, what standards do you follow?).

  • Provide examples of expected styles