#
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.
These are popular formats that are easy to use, and are well-supported by GitLab: you can embed markdown and mermaid diagrams in your GitLab README.md file, or directly in your project Wiki!
#
Markdown
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.
All the content on this website is generated from Markdown using the Retype framework. Markdown has become the de-facto standard for informal technical documentation.
#
Syntax
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.
#
Example
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.
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:
By convention, Markdown files should end in
.md. For example, README.md in your project root should be a Markdown formatted text file.
#
Mermaid.js
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.
#
Syntax
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:
#
Examples
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.
#
Design
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]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!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 --> [*]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()
}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()
}
#
Requirements
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: Mejourney
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
#
Project Management
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 : 24dgantt
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 : 24dHere'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 : Twittertimeline
title History of Social Media Platform
2002 : LinkedIn
2004 : Facebook
: Google
2005 : Youtube
2006 : Twitter
#
Misc
A mindmap of this course!
mindmap
root((Topics))
Design
Architecture
Principles
Design patterns
SOLID
Practices
Design reviews
Unit testing
Pair programming
Git branching
Merge requests
Refactoring
Code reviews
Toolchain
IDE
Gradle
JUnit
Docker
Mermaid
Programming
Concurrency
Databases
Web services
Cloud
Kotlin
OO programming
Functional programming