Skip to content
This repository was archived by the owner on Jun 15, 2024. It is now read-only.

Documentation

Jump to bottom
nh916 edited this page Mar 27, 2023 · 2 revisions

Documentation

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.
  • 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



Technologies Used

CI/CD

Every time a push is made to the docs branch, a GitHub actions watching docs branch for changes automatically starts running, builds the documentation, and pushes it to gh-pages branch. The gh-pages branch is also being watched for changes, and any time there is a change then it reloads the CRIPT Excel Uploader documentation based off of the new push to gh-pages branch.

The GitHub actions file for building of the docs 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/
    • Contains all the documentation written in markdown and html
    • Colors, icons, diagram, charts can be a helpful way of explaining concepts
  • 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

CRIPT Excel Template

The documentation pulls the CRIPT Excel Uploader template and all the executables from the latest release's assets

Clone this wiki locally