Documenting our Software Systems

Documenting our Software Systems

Documentation

  1. Each Service should have an entry in the Knowledge Base.
  2. The Knowledge Base is all open to the public. No secrets.
  3. You can make small edits in the Knowledge Base via GitLab (the edit button at the bottom of the page). For larger edits clone the repo.
  4. The repo uses only a master branch for simplicity. This is a trade-off.
  5. The website is build using Hugo. Install it if you want to edit the site on your machine.
  6. The site is automatically built with CI and published to https://crossref.gitlab.io/knowledge_base
  7. To create a new service:
    1. Each service should be a directory under content/docs/services. The name of the directory (e.g. crossmark-dialog) is the identifier used to refer to the service.
    2. _index.md, leave empty. This is required for the directory struture.
    3. about.md with a table of contents (work from another service’s frontmatter as a starter). Ensure the servicedeps and datadeps lists are completed. Service Dependencies are things that this service connects to. Data Dependencies are services where data comes from. They are often subtly different.
    4. Fill out the tag list to help cross-linking.
    5. Run hugo at the command line to check that the links are all correct. This will verify that there are no typos in your servicedeps or datadeps.
    6. After pushing, check that your checkin didn’t break the CI build.
  8. To preview locally run hugo serve and visit http://localhost:1313
  9. Periodically run python3 format.py --lint to update pages with the necessary front-matter items and generally clear up.