Best Practices#
This page aggregates best practices and helpful information for use when contributing to our documentation.
Our Cal-ITP Data Services Documentation uses the Jupyter Book ecosystem to generate our docs. You can find their full resources at this link: Jupyter Book Documentation.
Universal Rules#
There are a few things that are true for all files and content types. Here is a short list:
Files must have a title. Generally this means that they must begin with a line that starts with a single #
Use only one top-level header. Because each page must have a clear title, it must also only have one top-level header. You cannot have multiple headers with single # tag in them.
Headers should increase linearly. If you’re inside of a section with one #, then the next nested section should start with ##. Avoid jumping straight from # to ###.
Guidelines by Contribution Size#
Read below for guidance based on the size of your contribution.
When you are ready to make changes, visit the Submitting Changes section for how to contribute, and utilize the Common Content section for information on adding specific types of content.
Small Changes#
For small changes such as typos, clarification, or changes within existing content you can reference the Common Content section as needed.
New Sections (Headers)#
If you feel a new section is warranted, make sure you follow Jupyter Book’s guidelines on headers:
Headers should increase linearly. If you’re inside of a section with one #, then the next nested section should start with ##. Avoid jumping straight from # to ###.
New Pages and Chapters#
Add new pages and chapters only as truly needed.
If you are adding new pages or chapters, you will need to also update the _toc.yml file. You can find more information at Jupyter Book’s resource Structure and organize content.
You will also need to follow Jupyter Book’s guidelines for when adding files:
Files must have a title. Generally this means that they must begin with a line that starts with a single #
Use only one top-level header. Because each page must have a clear title, it must also only have one top-level header. You cannot have multiple headers with single # tag in them.