Guidance: Docs-As-Code#

Introduction#

This document describes how to write and publish documentation using the SCORE Docs-As-Code approach.

Diagrams#

The SCORE Docs-As-Code solution supports several ways to create diagrams. Each has its own strengths and weaknesses.

Draw.io#

Draw.io can be used to create diagrams in a graphical editor.

The easiest way to use Draw.io is to create a new file in VS Code and use the Draw.io extension. The new file must be named with the .drawio.svg extension. When you click on the file, the Draw.io editor will open within VS Code:

Draw.io Editor in VS Code

Then you can embed the image in .rST files like this:

.. image:: assets/docs-as-code/example.drawio.svg
   :alt: Example Diagram

Which will render like this:

Example Diagram

PlantUML#

PlantUML can be used to create diagrams in a text-based format. The diagrams are rendered as images in the documentation.

You can use them inline in markdown files like this:

.. uml::

   @startuml
   Alice -> Bob: Authentication Request
   Bob --> Alice: Authentication Response
   @enduml

Which will render like this:

Alternatively you can include them as .puml files like this:

.. uml:: assets/docs-as-code/example.puml
   :alt: Example Diagram

Which will render like this: