Documentation

You will spend considerable time on your project writing documentation. Writing effective documentation will help you communicate more effectively with project stakeholders. There are many forms of documentation that we care about:

• Project documentation: Tracking project details to help us remember our project constraints. Useful for planning later phases. e.g., Issues lists; Milestones; Project plans; Gantt charts.
• Design documentation: Why we made specific design decisions; materials to help new developers understand rationale. e.g., UML diagrams; design documents.
• Code documentation: Inline documentation (code comments) to explain peculiarities of an implementation.
• User documentation: Help users understand how something works! e.g., how to install; what features exist; what has changed in a new release.

Technologies

We will use two fundamental technologies to write our documentation: Markdown, a plain-text markup language, and Mermaid, a text-based diagramming language. We gravitate towards text-based solutions (over something like MS Word) because we can store these in Git, and it’s easy to manage them since they’re just text files.

Markdown and Mermaid are both supported by GitLab, IntelliJ with the markdown plugin and other development tools like VS Code e.g., you can produce a Markdown document containing Mermaid diagams, and those tools can display it correctly.

Markdown

Markdown was originally designed as a quick way of authoring web pages and was meant to be transpiled to HTML. Since its debut in 2004, it’s been quickly adopted as a standard for technical documentation. It’s far from a perfect specification, but it’s useful and human-readable.

Markdown uses simple text annotation in a text document to indicate the structure. e.g., here’s the Markdown from the beginning of this section: The ## symbols denote a heading, and the * indicate bullet points. The []() syntax is for an external link. See the Markdown Guide for syntax details.

## Getting Started

We will use two fundamental technologies to write our documentation:
* [Markdown](https://www.markdownguide.org): a plain-text markup language, and 
* [Mermaid](https://mermaid.js.org/intro/): a text-based diagramming language.

Mermaid

Mermaid is a text format for producing diagrams. It’s declarative: you describe the componets of the diagram, and the mermaid engine handles layout. Mermaid diagrams are supported by your toolchain, and you can embed diagram syntax directly in a Markdown document.

Mermaid supports a large number of diagram types, including basic flowcharts, sequence diagrams, class diagrams and even project diagrams like timelines and Gantt charts. See the Mermaid documentation for examples.

Here’s some simple examples taken from the documentation:

Embedded in a Markdown document:

```mermaid
graph TD;
    A-->B;
    A-->C;

  graph TD;
    A-->B;
    A-->C;

---
title: Animal example
---
classDiagram
    note "From Duck till Zebra"
    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()
    }

  ---
title: Animal example
---
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()
    }

Types of Documents

We will mostly write Markdown documentation in GitLab wiki pages, or occasionally to embed diagrams in our README.md file or other project documentation e.g., many of my samples have Mermaid design diagrams in their README file.

Code Comments

See Handling Code for a discussion on code comments (which aren’t written in Markdown). Code comments are generally 1-2 sentences, meant to describe a particular block of code.

Code Documentation

For larger comment blocks e.g., a design recipe, you should use KDoc. KDoc supports more complex comment blocks, where you can identify code elemetns likke classes, parameters, properties, constructors and so on. You can then use a tool like Dokka to generate comprehensive code documentation! This is generally not something you would do when writing an application, but can be extremely useful if you need to document your api e.g., building a library or a web service.

e.g., the Kotlin coroutine libraries are documented using Dokka.

UML Diagrams

Mermaid.js can be used to crate UML diagrams in a markdown file or a Wiki page. They cannot be added to source code directly, but can certainly be placed in a markdown-based design document for that code.

The following diagrams are particularly useful when documenting a system:

• Flowcharts or Block diagrams can be used to document a system structure e.g., modules or components.
• Class diagram for documenting classes and relationships.
• State diagram demonstrating transitions between states.

These diagrams can be useful for documenting a project.

• Gantt chart to show a plan or schedule.
• Timeline illustrates a chronology of events. Alternative to a Gantt chart.
• User journey diagrams show important workflows (sequences of actions) from the user’s perspective. They can be decomposed into a set of related requirements.

  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 Another :2014-01-12, 12d
        another task    :24d

An example of a Gantt chart from the Mermaid documentation.

README.md

The first document you will need to produce is the README.md file for your GitLab project. This is a Markdown file that should be in the root of your Git project (and it will be the page displayed when your Gradle project page opens).

Creating this file is discussed on the Gradle Project page.

It is important that you include the content specified when you create this page. You are allowed to add additional content if it is useful, e.g., adding project documents like a Gantt chart or a basic class diagram to illustrate your project structure.