From 4236b8266fcddf71caef806edefe6df69a377975 Mon Sep 17 00:00:00 2001 From: jeffgillan <jgillan@arizona.edu> Date: Wed, 18 Sep 2024 10:45:00 -0700 Subject: [PATCH] streamlined documentation --- docs/03_documentation_communication.md | 31 ++++++++++++++++---------- 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/docs/03_documentation_communication.md b/docs/03_documentation_communication.md index eded2d6e7..39471efe0 100644 --- a/docs/03_documentation_communication.md +++ b/docs/03_documentation_communication.md @@ -29,15 +29,6 @@ <br/> <br/> -### Tips for Great Documentation -- **:material-glasses: Clarity**: Documentation should be easy to understand with clear language and no ambiguity. -- **:octicons-circle-16: Completeness**: It must cover all essential details, leaving nothing crucial undocumented. -- **:fontawesome-solid-bullseye: Accuracy**: Information should be up-to-date and correct to prevent errors and misunderstandings. -- **:simple-instructure: Organization**: A logical structure and clear organization make it easy to navigate and find information. -- **:fontawesome-solid-exclamation: Relevance**: Documentation should focus on what's pertinent to its intended audience or purpose, avoiding unnecessary information. - - -Not all documentation is the same. **The documentation system**, by Divio, categorizes the different types of documentation into 4 quadrants: <figure markdown> <a href="https://documentation.divio.com/" target="blank" rel="xkcd">![xkcd](./assets/documentation.webp) </a> @@ -51,6 +42,21 @@ Not all documentation is the same. **The documentation system**, by Divio, categ - **References**: References offer technical descriptions of the machinery and how to operate it. References have one job only: to describe. They are code-determined, because ultimately that’s what they describe: key classes, functions, APIs, and so they should list things like functions, fields, attributes and methods, and set out how to use them. - **Explanation**: Discussions! The aims of explanations are to clarify and illuminate a particular topic by broadening the documentation’s coverage of a topic. +<br/> +<br/> + +### Tips for Great Documentation +- **:material-glasses: Clarity**: Documentation should be easy to understand with clear language and no ambiguity. +- **:octicons-circle-16: Completeness**: It must cover all essential details, leaving nothing crucial undocumented. +- **:fontawesome-solid-bullseye: Accuracy**: Information should be up-to-date and correct to prevent errors and misunderstandings. +- **:simple-instructure: Organization**: A logical structure and clear organization make it easy to navigate and find information. +- **:fontawesome-solid-exclamation: Relevance**: Documentation should focus on what's pertinent to its intended audience or purpose, avoiding unnecessary information. + + + + + + <br/> ### Public Repositories for Documentation @@ -140,10 +146,8 @@ Not all documentation is the same. **The documentation system**, by Divio, categ --- -## :material-antenna: Communication - +## :material-antenna: Public Communication -### External (Public) Communicating with the public and other members of your science community (in addition to traditional peer-review publications and conferences) is one of the most important parts of your science! @@ -168,6 +172,9 @@ There are many ways scientists use social media and the web to share their data organization you work for and may be used in decisions about hiring or dismissal. +<br/> +<br/> + --- ## Hands-on: Building a GitHub Pages Website using MkDocs