From fc6b25e5b33c35d2fe4c02ec0580e56b319a09e7 Mon Sep 17 00:00:00 2001 From: Maxine Hartnett Date: Fri, 9 Jan 2026 14:25:52 -0700 Subject: [PATCH 1/3] Add how-to page --- docs/source/how_to_write_docs.md | 43 ++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 docs/source/how_to_write_docs.md diff --git a/docs/source/how_to_write_docs.md b/docs/source/how_to_write_docs.md new file mode 100644 index 0000000..6507bc0 --- /dev/null +++ b/docs/source/how_to_write_docs.md @@ -0,0 +1,43 @@ +# How to write technical documentation + +## Overview/main goals + +The main goals of our technical documentation are: + +- **Be clear**: Documentation should be easy to read and understand, with acronyms defined and referenced information linked out +- **Be findable**: Documentation pages should be in a logical location, with clear focus and scope, and an accurate title +- **Be in existence**: Documentation should be created, rather than not. This also means that it should be easy to write documentation, without excessive requirements, rules, or expectations +- **Be accurate**: This goal is aided by the first two goals, but it also requires a team commitment to remove or correct inaccurate documentation. It is better to have no documentation than it is to have inaccurate documentation, so delete anything you see that is wrong. + +This documentation should be focused on internal team members, without worrying about external partners, but it should also be easy to read for even new team members who have very little context or background knowledge. + +## Rules and Best Practices + +- Documentation pages should be short and refined in scope. This helps with goals 1 + 2, by making each piece of information in a page directly related to the title, and to make linking information in other pages easier. +- Be cautious about adding additional broad categories or top-level pages. This helps with goal 2, by making sure it is easy to start a search at a high level and dig down. Try to keep organization flat. +- In existence is better than perfect. A documentation page doesn't need to be complete. It doesn't need to cover every piece of information. Having an incomplete page is better than no page. This ties into rule 3. If you aren't sure about something, write it down anyway and note that. +- If you're writing out a long explanation or context, make a docs page and link it instead. Instead of having broader context, technical designs, or frequently asked questions scattered across the ephemeral world of tickets, slack messages, and emails, create it once and link it from then on. +- It should be easy to create documentation. This ties into rule 3 and 1. It should be easy to create documentation, without excessive requirements or rules either from the team or from yourself. +- Correct or remove outdated information as you find it. The other side of making documentation easy to write is making it easy to remove. Every team member should feel empowered to move, edit, or delete any and all pages. Again, missing information is preferable to inaccurate documentation. All documentation is ephemeral. +- Reduce the amount of duplicate information. Writing something down in multiple places makes it more difficult to find, and makes it harder to correct. Ways to reduce this happening are 1) keeping pages short 2) linking instead of making subsections and 3) combining pages if you do find duplicates. +- Avoid "misc" or catch-all pages or places. These make finding and organizing information very difficult. + +## Types of Pages + +This is a brief description of some of the pages that you may find or create within this sphere. Not every page neatly fits into these categories and they are not prescriptive. + +### Overview Pages + +These are basic descriptions of the world as it is. This could describe relationships with external partners, background on the mission, documentation on the existing design of infrastructure. Resist the urge to make this too detailed - it shouldn't replace documentation of the code, but should instead act as an easy place to point people if they ask questions like - "what is the camera radiometry? What is it doing? When should it be used?" + +### Flow diagrams + +Similarly to overview pages, these are images or flow diagrams which supplement overview pages. These can be a powerful visualization for difficult to convey information. + +### How-to pages + +These are descriptions of how to accomplish a specific task. This might include "how to open a pull request" or "how to fix this specific bug" + +### Design Documents and Whitepapers + +These are documents which describe some proposed future work or a future design. They can be as detailed as including a complete description of future work and the roadmap to get there, or as simple as a comparison between two technologies or a proposed solution for a problem. The key factor is that they are for future work, and therefore, should try to avoid descriptions of existing designs. Rather, they should link out to existing overview pages, to reduce duplicate work and ensure that any new information is not lost once the design doc is complete and no longer used. From 08b12c6b00943c6d35b37b1425a08b765106d855 Mon Sep 17 00:00:00 2001 From: Maxine Hartnett Date: Fri, 9 Jan 2026 14:52:23 -0700 Subject: [PATCH 2/3] remove bad pre-commit tool --- .pre-commit-config.yaml | 6 ------ docs/source/how_to_write_docs.md | 12 ++++++------ 2 files changed, 6 insertions(+), 12 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 756f66a..b49a93f 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -19,9 +19,3 @@ repos: hooks: - id: codespell files: ^.*\.(md|rst|yml)$ - - repo: https://github.com/markdownlint/markdownlint - rev: v0.11.0 - hooks: - - id: markdownlint - files: ^.*\.(md)$ - update: false \ No newline at end of file diff --git a/docs/source/how_to_write_docs.md b/docs/source/how_to_write_docs.md index 6507bc0..2b1acee 100644 --- a/docs/source/how_to_write_docs.md +++ b/docs/source/how_to_write_docs.md @@ -6,19 +6,19 @@ The main goals of our technical documentation are: - **Be clear**: Documentation should be easy to read and understand, with acronyms defined and referenced information linked out - **Be findable**: Documentation pages should be in a logical location, with clear focus and scope, and an accurate title -- **Be in existence**: Documentation should be created, rather than not. This also means that it should be easy to write documentation, without excessive requirements, rules, or expectations -- **Be accurate**: This goal is aided by the first two goals, but it also requires a team commitment to remove or correct inaccurate documentation. It is better to have no documentation than it is to have inaccurate documentation, so delete anything you see that is wrong. +- **Be in existence**: Documentation should be created, rather than not. This also means that it should be easy to write documentation, without excessive requirements, rules, or expectations +- **Be accurate**: This goal is aided by the first two goals, but it also requires a team commitment to remove or correct inaccurate documentation. It is better to have no documentation than it is to have inaccurate documentation, so delete anything you see that is wrong. This documentation should be focused on internal team members, without worrying about external partners, but it should also be easy to read for even new team members who have very little context or background knowledge. ## Rules and Best Practices -- Documentation pages should be short and refined in scope. This helps with goals 1 + 2, by making each piece of information in a page directly related to the title, and to make linking information in other pages easier. +- Documentation pages should be short and refined in scope. This helps with goals 1 + 2, by making each piece of information in a page directly related to the title, and to make linking information in other pages easier. - Be cautious about adding additional broad categories or top-level pages. This helps with goal 2, by making sure it is easy to start a search at a high level and dig down. Try to keep organization flat. - In existence is better than perfect. A documentation page doesn't need to be complete. It doesn't need to cover every piece of information. Having an incomplete page is better than no page. This ties into rule 3. If you aren't sure about something, write it down anyway and note that. - If you're writing out a long explanation or context, make a docs page and link it instead. Instead of having broader context, technical designs, or frequently asked questions scattered across the ephemeral world of tickets, slack messages, and emails, create it once and link it from then on. -- It should be easy to create documentation. This ties into rule 3 and 1. It should be easy to create documentation, without excessive requirements or rules either from the team or from yourself. -- Correct or remove outdated information as you find it. The other side of making documentation easy to write is making it easy to remove. Every team member should feel empowered to move, edit, or delete any and all pages. Again, missing information is preferable to inaccurate documentation. All documentation is ephemeral. +- It should be easy to create documentation. This ties into rule 3 and 1. It should be easy to create documentation, without excessive requirements or rules either from the team or from yourself. +- Correct or remove outdated information as you find it. The other side of making documentation easy to write is making it easy to remove. Every team member should feel empowered to move, edit, or delete any and all pages. Again, missing information is preferable to inaccurate documentation. All documentation is ephemeral. - Reduce the amount of duplicate information. Writing something down in multiple places makes it more difficult to find, and makes it harder to correct. Ways to reduce this happening are 1) keeping pages short 2) linking instead of making subsections and 3) combining pages if you do find duplicates. - Avoid "misc" or catch-all pages or places. These make finding and organizing information very difficult. @@ -32,7 +32,7 @@ These are basic descriptions of the world as it is. This could describe relation ### Flow diagrams -Similarly to overview pages, these are images or flow diagrams which supplement overview pages. These can be a powerful visualization for difficult to convey information. +Similarly to overview pages, these are images or flow diagrams which supplement overview pages. These can be a powerful visualization for difficult to convey information. ### How-to pages From fe6ff7461782ea6caabbefaf6702a89459505ffe Mon Sep 17 00:00:00 2001 From: Maxine Hartnett Date: Mon, 12 Jan 2026 09:46:50 -0700 Subject: [PATCH 3/3] Updating index to point at new page --- docs/source/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/index.rst b/docs/source/index.rst index ec429e2..4188d88 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -51,6 +51,7 @@ Contents .. toctree:: :maxdepth: 1 + how_to_write_docs licensing programming_languages/index data_management/index