# 1. Create a fork of the repository (the fork button is on the upper right corner on GitHub)
# 2. Clone the repository to your local machine, replace <fork url> with your own fork.
git clone <fork url>
cd asc-public-docs/
# 3. Create a branch to track your work
git checkout -b your-branch-name
# 4. install dependencies
pip install -r requirements.txt
# 5. Make your changes to the code
# See "Adding Your Files" in the readme for details
# ...
# 6. Preview your changes, in the root of the repo run
mkdocs serve
To contribute changes back in:
# 1. push changes back into your fork
git push origin your-branch-name
# Create a PR on this repository
See mkdocs material docs for information on how to work with mkdoc's material theme and it's features.
mkdocs.yml
, add a new file somewhere appropriate under nav:
mkdocs serve
to check if your file(s) rendered correctly.Contributors should consider writing new docs under one of our four categories:
We use these four categories to cover the range of potential docs while clarifying to authors and readers for what kind of documentation goes where.
Getting Started | How-Tos | Concepts | Manuals | |
---|---|---|---|---|
Oriented To | Learning | Achieving a Goal | Understanding | Referencing |
Composed As | Step-by-Step Jupyter or Similar Tutorial | General Purpose Guide | Written Summary | Generated Sphinx/Doxygen Site |
Has the Goal of | Enabling Beginners | Showing How To Solve A Problem | Give Detailed Written Explanations | Give Dry Descriptions of Libraries, Services and Apps |
Example | Jupyter notebook with toy data on how to ingest and project images | A breakdown of quirks working with Themis Images | Write-up on how ISIS defines projections | ISIS library Doxygen reference |
This website structure borrows from the Divio documentation system, except adapted to more specifically adhere to how our software is already structured, renamed the categories to be more specific, and have more focus on the composition (or mode of writing) of the docs to reduce ambiguity. One can't expect any categorical structure for software documentation to be orthogonal to each other. There will always exist some degree of overlap between categories as the quantity of documentation grows. Documentation in one category can easily have overlapping information with those in others. However, composition of the doc (e.g., jupyter notebook with an explicit starting and end point, short how-to guide with code examples but ambiguous starting point and end point, written explanation without code, doxygen API reference) is less ambiguous that whether or not your docs can be considered a guide or a tutorial.
These are longer "learn by doing" exercises that users can follow to learn some extended process using the libraries. These should have the user execute code or run commands from the library to complete a task.
Good getting started docs should:
Concrete things your tutorial needs:
Examples:
How-to guides are much like recipes in a recipe book. Write how-to docs to solve specific problems quickly, sometimes copy-pastable. Think of how-to guides as pre-emptive StackOverflow-like problems.
Similar to getting started guides in that they explain to users how to perform some valuable tasks with the software, but distinct in that they:
Examples:
Concept docs are understanding-oriented docs. The focus is on explaining a topic. These expand the user's understanding of a topic without elaborating on particulars of code while providing context or descriptions. Information from concept docs might be among other docs, but getting started docs, how-to guides, or software manuals can reference concept docs that go in-depth on the topic.
Good concept docs have:
Examples:
Software manuals centered on the code of the library. These are generally links to the library's programmatically generated API docs. Think Sphinx docs and/or Doxygen-generated docs.
Examples: