#Markdown Documentation

Technical documentation is an important part of your project! Although you aren't expected to write exhaustive documentation most of the time, we often need to record important ideas, or communicate with other team members. Usable documentation really helps.

Examples of useful documents that you will likely encounter in a software project include:

• Project documents, detailing project constraints, timelines, and so on.
• Requirements documents, detailing the requirements that you are expected to deliver.
• Design documents that explain how some critical system works. You should be writing these when planning out features: both as a way to share your design with your team-mates, and as a way to record the details for reference later (remember: we're always plan to maintain systems long-term).
• User documents, explaining how to use your software.
• Product release documents, including Release Notes, README files.

We'll discuss using Markdown for technical documents, and Mermaid.js for embedding diagrams.

Markdown is a markup language that allows you to add formatting elements to a text file. The elements that you can add are reminiscent to HTML elements, which makes sense - Markdown was designed to be easily convertable to HTML (which is itself also a markup language). The basic syntax is here.

Markdown supports the following tags:

When Markdown is used in GitLab, either in a file or a Wiki page, the renderer is able to display formatted text! This makes it beneficial when writing technical documentation.

For example, in my editor I can add a paragraph with a bunch of styling:

#### Sub-sub-sub-sub-heading
I can write some:
* **bold** text
* _italicized_ text

I can even add an image.
![image caption](architecture-needs.png)

This gets displayed in my editor's preview window like this:

Authoring a Markdown document can be done in any text editor, but you might appreciate an editor that has syntax highlighting and a live preview. These all work well:

• IntelliJ IDEA with a plugin
• VS Code
• Typora.

By convention, Markdown files should end in .md. For example, README.md in your project root should be a Markdown formatted text file.

We often add diagrams to documents to clarify and communicate additional information. These can include Gantt charts or burn-down charts for project tracking; illustrative graphs when determining requirements, and a variety of diagrams during the design and implementation phases.

Mermaid is a Javascript-based charting tool that can convert Markdown diagramming notation into diagrams.

The advantage to using Mermaid.js is that your diagrams are completely described in Markdown. GitLab also renders Mermaid.js diagrams easily, so you can use them directly in your project README file, or any of your Wiki pages to render inline diagrams.

The editors described above all support Mermaid.js rendering. You might also want to try the Mermaid live editor. It generates raw mermaid syntax, which you can then add to an existing Markdown document.

The GitLab built-in Web IDE doesn't seem to recognize Mermaid diagrams. However, if you edit the file in a supporting editor, it will display the diagram properly, and it will be rendered properly when the Markdown is viewed in GitLab.

This is a short list of diagrams taken directly from the Mermaid Documentation. See that page for a more complete reference.

To render diagrams in Markdown, they need to be embedded as a code block element. Markdown uses three backticks to start and end a code-block. After the first three backticks, you enter the language name, in this case mermaid, followed by the diagram syntax, and then three final backticks to close it.

The diagram syntax is a diagram type, followed by a flow indicator. e.g. flowchart LR for a flowchart flowing left-to-right (indicators include LR, RL, TB, BT). For example, here's a simple flowchart, placed in the middle of some text in a Markdown document.

This would produce output like this:

Here are detailed examples of diagrams that can be created in Mermaid.js. For an exhaustive list of diagrams with examples, see the official Mermaid Documentation.

Here's a flowchart diagram showing program execution.

flowchart TD
    A[Start] --> B{Is it?}
    B -->|Yes| C[OK]
    C --> D[Rethink]
    D --> B
    B ---->|No| E[End]

Sequence diagrams commonly show how processes communicate with one another. They are great for showing ordering effects.

sequenceDiagram
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
    Alice-)John: See you later!

State diagrams can be useful for illustrating transitions between states in a program.

stateDiagram-v2
    [*] --> Still
    Still --> [*]

    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]

Here's the class diagram syntax and some examples.

classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal <|-- Zebra
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    Animal: +mate()
    class Duck{
        +String beakColor
        +swim()
        +quack()
    }
    class Fish{
        -int sizeInFeet
        -canEat()
    }
    class Zebra{
        +bool is_wild
        +run()
    }

User Journey Diagrams are a useful way to show a series of steps that a user might take to perform an operation in your software.

journey
    title My working day
    section Go to work
      Make tea: 5: Me
      Go upstairs: 3: Me
      Do work: 1: Me, Cat
    section Go home
      Go downstairs: 5: Me
      Sit down: 5: Me

Here's the Gantt chart syntax.

gantt
    title A Gantt Diagram
    dateFormat  YYYY-MM-DD
    section Section
    A task           :a1, 2014-01-01, 30d
    Another task     :after a1  , 20d
    section Another
    Task in sec      :2014-01-12  , 12d
    another task      : 24d

Here's a timeline diagram, which is also useful for project tracking.

timeline
    title History of Social Media Platform
    2002 : LinkedIn
    2004 : Facebook
         : Google
    2005 : Youtube
    2006 : Twitter

A mindmap of this course!