Documentation

Documentation Guide

Suggestions

• Documentation should be concise as long walls of text creates bad UX.
• Language should be simple, explicit, and unmistakable.
• Documentation uses simple vocabulary to avoid confusion.
• Every page is consistent.
  • Consistency makes finding information very easy and clean.
• The navigation should be easy to see.
  • Long or wordy navigations makes it harder to navigate through.
• Sections should be clearly labeled as what they are
• It should not overwhelm the user with unnecessary information.
• There should be pictures, icons, and notes where available to walk the user through the software.
• User should find everything they need from a simple glance.
• Things that should get users attention should be get the users attention such as using Warning or other widgets.
• There should be bullet/numbered lists where possible as they are easy to glance and grasp.
• There should be simple code examples for the user to learn how to interact with the software.
• Variable names can sometimes be confusing for a first time user because they are unsure if data_object is functionality or just a plain variable we made up for the example.
  • Try to use my_data_object to show that it is just an example.
• Good grammar and punctuation are always nice, but not a big deal.
• Repetition is generally okay because it helps teach and reaffirms what the user knows.
• You know your documentation is good when you can easily refer to it whenever you or anyone else is lost and it quickly makes everything very clear.
• Good documentation should be up to date
  • It would be bad if the documentation is giving the wrong advice and even worse would be if different sources are giving different information because the documentation is outdated.
• When describing nodes try to link to the page in the manual that has full text for the node and can give some more information
  • Such as using the syntax of:

https://pubs.acs.org/doi/suppl/10.1021/acscentsci.3c00011/suppl_file/oc3c00011_si_001.pdf#page=<PAGE NUMBER>

Good Examples

• Google has some of the best documentation.
  • Google Maps API documentation
  • Gmail Documentation
• Django Documentation
• React Native Documentation
• Digital Ocean Django deployment documentation
• Java Docs can be good too.

Technologies Used

• The documentation for Python-SDK utilizes Material MKDocs.

CI/CD

The GitHub workflow file for building of the docs and pushing it to gh-pages can be found in .github/workflows/docs.yml, it largely comes from the Material MkDocs documentation regarding CI/CD

Files

• mkdocs.yml
  • Contains settings, plugins, theme that is used throughout the documentation
  • Contains the navigation for the whole documentation
• requirements_docs.txt
  • Contains all python packages needed for the documentation
  • GitHub actions installs all requirements.txt whenever triggered
• docs/
  • Can contain documentation written in markdown and html
  • Colors, icons, diagram, charts can be a helpful way of explaining concepts
  • in majority of places it is ::: cript.nodes.primary_nodes.project which means to get the documentation from the docstrings of that file
• docs/stylesheets/extra.css
  • Contains the css that every page has

Running Docs Server Locally

To run mkdocs locally follow these steps:

1. Install docs dependencies
   • pip install -r requirements_docs.txt
2. Start server
   • in the terminal type: mkdocs serve

CI/CD

within .github/workflows/docs.yaml is the workflow to build the documentation from docstrings within src/cript/ and MD files then push to the built html and css to gh-pages branch. The repository is configured to listen to the gh-pages branch for any pushes. Once there has been a push to gh-pages GitHub pages deploys deploys the new changes to the repositories GitHub pages URL