Documenting our Software Systems
- Each Service should have an entry in the Knowledge Base.
- The Knowledge Base is all open to the public. No secrets.
- 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.
- The repo uses only a
master branch for simplicity. This is a trade-off.
- The website is build using Hugo. Install it if you want to edit the site on your machine.
- The site is automatically built with CI and published to https://crossref.gitlab.io/knowledge_base
- To create a new service:
- 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.
_index.md, leave empty. This is required for the directory struture.
about.md with a table of contents (work from another service’s frontmatter as a starter). Ensure the
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.
- Fill out the tag list to help cross-linking.
hugo at the command line to check that the links are all correct. This will verify that there are no typos in your
- After pushing, check that your checkin didn’t break the CI build.
- To preview locally run
hugo serve and visit http://localhost:1313
- Periodically run
python3 format.py --lint to update pages with the necessary front-matter items and generally clear up.