Documentation

The purpose of this internal documentation is to centralize our knowledge base across the Dev Team.

How to add documentation?

1. Go to the api/internal-docs/docs folder of the source code inside the api repository.
2. Add your markdown in a dir. Each dir represents a group on the sidebar and each markdown file represents a sub-section in that group.
3. Make sure to add the _category_.json file inside the folder, for the section's metadata.
4. At the top-level of each markdown file make sure to add the sidebar_position: to properly order the sub-sections
5. If you need to add images to your docs, inside internal-docs/docs/img folder, create a new dir for your section and add all your images there. Inside your markdowns you can reference the images you added by their relative path.

How documentations are deployed/published?

When you open a PR that includes internal-docs/docs changes, Cloudflare will handle building the docs.

Any errors or failed builds will be flagged in the PR's preview.

Once the PR is merged to origin/main, Cloudflare will handle deployment.

Best Practice for writing internal docs for the team

1. Keep documentation short and easy to read; include diagrams (flowcharts, use cases, UML, sequences, ...) using mermaid.
2. If the feature you are documenting is large, divide the documentation into multiple short sections.
3. You can include documentation for a feature you are working on in the same branch/PR. Once the branch is merged, the documentation will be automatically deployed.
4. For features that are already merged and you need to add docs later, open a new branch/PR that only has the internal-docs changes. Try to keep large code changes separate by function and service in the api repository.
5. Don't make AI write all your documentation; try to use your own wording and simple expressions to break down technical jargon.
6. Inform the Dev Team when a new documentation folder is added to share knowledge.