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 :doc:`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 :doc:`doc_templates/doc_styleguide_template` - 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