Link Search Menu Expand Document

Documentation System

“If it isn’t documented, it isn’t done.” - Cody Burleson

Product Documentation

All product documentation is published to a static site created with Jekyll (https://jekyllrb.com/) and made available at the following URL:

https://codyburleson.github.io/rmtn/

  • Even though this repository is private, the static product doc site is public!
  • The Jekyll project is found within the monorepo at ./docs.
  • The Jekyll project configuration can be found in ./docs/_config.yml
    • In the config file, you will note that we currently leverage a remote theme (source code pulled from GitHub) called Just the Docs. It is configued by the line:
      • remote_theme: pmarsceill/just-the-docs
      • Note that we could fork this repo in the future and point to our own fork if we found the need to customize it further.
  • Update and publish documentation independently from the docs branch only and don’t forget to merge docs frequently back into main

Publishing the Product Documentation Site

To update documentation, publish documentation changes to the docs branch: - Ensure you are working in the docs branch using git checkout docs - Make changes in the ./docs directory (the Jekyll project) - Stage and commit changes with a commit message similar to “Update documentation” (don’t just write “update” because the context will not be clear when the docs branch gets merged back into other branches) - Publish using git push origin docs (this publishes only the docs branch and kicks off the Jekyll build process for GitHub pages)

This works because we have configured the ./docs directory and docs branch to feed GitHub pages as shown below.

GitHub Pages Configuration

The configuration screen shown above can be accessed at the following URL:

https://github.com/codyburleson/rmtn/settings/pages