Solutions Playbook

Appearance

VitePress ​

Know what? You're looking at VitePress right now! It is asuprt lightwieght and powerful static site builder, and wonderful for building out documentation like this.

Helpful resources ​

How we use VitePress ​

We use VuePress to publish documentation for quick reference as a team, and for specific application developer documentation.

Structuring documentation ​

Folder structure ​

To keep thing organised we use a folder structure to categories documentation. This is also helpful when building out the sidebar.

index.md
| folder_1
| - doc_1.md
| - doc_2.md
| folder_2
| - doc_3.md

Based off the folder structure we can build a sidebar that categorises documentation into helpful areas

themeConfig: {
    sidebar: [
      {
        text: "Folder 1",
        items: [
          { text: "Doc 1", link: "/folder_1/doc_1" },
          { text: "Doc 2", link: "/folder_1/doc_2" },
        ],
      },
      {
        text: "Folder 2",
        items: [
          { text: "Doc 1", link: "/folder_2/doc_3" },
        ],
      },
    ],
  },

Adding images ​

To add static assets like images/files we add them in the folder of the referencing document within an images folder using the following convention:

{document_name}_{image_name}.png

You can then reference them directly in the document:

![Image name](./images/{document_name}_{image_name}.png)

Making changes ​

There is no develop branch of the VuePress instance, all changes are merged to the main branch. Changes to VuePress documentation are categorised into two types

  • Standard
  • Hotfix

Standard changes ​

95% of the time your change will be a standard change. These can include:

  • Adding / removing new documentation page
  • Adding any structural changes to the documentation
  • Changing the configuration files of the documentation
  • Making an addition / significant ammendment to existing documentation

All standard changes need to be branched off and a pull request made to the main branch. Only the documentation owner needs to be added as a reviewer.

Hotfix changes ​

When you are making an insignificant change, you can do a hotfix change. These can include:

  • 1-2 line content changes / corrections
  • Spelling / format corrections

Hotfix changes can be commited straight to the main branch