Skip to content

Commit

Permalink
Update n00b-overview.md
Browse files Browse the repository at this point in the history
  • Loading branch information
NeilCuzon committed Oct 10, 2020
1 parent 19ac8e6 commit 35deb4a
Showing 1 changed file with 9 additions and 10 deletions.
19 changes: 9 additions & 10 deletions docs/overview/n00b-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,21 +5,20 @@ title: Overview

# Overview for Beginners

## There is no explanation like a Good Diagram
## Explaining with a Diagram

A picture is worth a thousand words, a good diagram would be worth more. There is no disputing that they are indeed very useful. Yet very few people use them, even fewer still do so, for documentation.
A picture is worth a thousand words, a good diagram would be worth more. There is no disputing that they are indeed very useful. Yet very few people use them, even fewer still do so for documentation. Mainly because it takes too much time that could be used for more important functions.

mermaid aims to change that.

## Creating and Maintaining Diagrams should not be an expensive and frustrating process.
## Creating and Maintaining Diagrams

Anyone who has used Visio, or (God Forbid) Excel to make a Gantt Chart, knows how hard it is to make, edit and maintain good visualizations.

In an environment of constantly changing information , diagrams/charts become obsolete/inaccurate very fast. This hobbles the information transfer and productivity in teams.
In an environment of constantly changing information , diagrams/charts are both very important and also become obsolete/inaccurate very fast. This catch-22 hobbles the information transfer and productivity in teams.

# Doc Rot kills Diagrams
# Doc Rot in Diagrams

The fast setting Doc-Rot in diagrams makes it quite hard to rationalize taking hours in a desktop application, to produce a diagram that you would need to recreate again the following week in order to account for updates and changes in the app you are documenting. Yet that is often the reality for diagrams and charts and the people who make them.
Doc-Rotis quite quick on diagrams makes, after a change is made, it quite hard to rationalize taking hours in a desktop application, to produce a diagram that you would need to recreate again the following week in order to account for updates and changes in the app you are documenting. Yet that is often the reality for diagrams and charts and the people who make them.

mermaid seeks to change that. mermaid is a javascript based tool that utilizes a markdown inspired syntax to generate documentation, which is actually quicker, less complicated and more convenient than most traditional diagramming software. This is a relatively straightforward solution to a major hurdle in software teams.

Expand Down Expand Up @@ -63,12 +62,12 @@ mermaid solves this by cutting the time, effort and tooling that is required to
Because, the text base for diagrams allows for it to be updated easily, it can also be made part of production scripts (and other pieces of code). So less time needs be spent on documenting, as a separate task.


## mermaid helps Documentation catch up with Development, in quickly changing projects.
## Catching up with Development

Being based on markdown, mermaid can be used, not only by accomplished front-end developers, but by most computer savvy people to render simple diagrams, at much faster speeds.
Being based on markdown, mermaid can be used, not only by accomplished front-end developers, but by most computer savvy people to render diagrams, at much faster speeds.
In fact one can pick up the syntax for it quite easily from the examples given and there are many tutorials in the internet.

## mermaid is for everyone.
## Mermaid is for everyone.
Video [Tutorials](./Tutorials.md) are also available for the mermaid [live editor](https://mermaid-js.github.io/mermaid-live-editor/).

For information on how to use mermaid, click [here](https://mermaid-js.github.io/mermaid/#/n00b-gettingStarted).
Expand Down

0 comments on commit 35deb4a

Please sign in to comment.