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.

Getting Started

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
    note for Duck "can fly\ncan swim\ncan dive\ncan help in debugging"
    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
    note for Duck "can fly\ncan swim\ncan dive\ncan help in debugging"
    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()
    }

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

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

  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

Types of Documentation

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).

README.md file

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.

Wiki pages

Wiki pages can be added in your GitLab project: Plan > Wiki.

• Markdown and Mermaid are supported in the Wiki.
• When project stages require you to add a wiki page, make sure to link that page to the top-level README file so that the TA can mark it.
• Feel free to add any additional project documents as Wiki pages.
• Give all pages meaningful names.