marcel/mermaid
1
0
Fork 0
mirror of https://github.com/mermaid-js/mermaid.git synced 2025-09-24 17:59:39 +02:00
Code Issues Packages Projects Releases Wiki Activity

Update n00b-overview.md

Browse Source
This commit is contained in:
Neil Cuzon
2020-07-19 21:18:36 -07:00
committed by GitHub
parent e15e34db93
commit 956ee06ea6
1 changed files with 15 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
docs/n00b-overview.md
View File

@@ -3,7 +3,21 @@
## Nothing explains a concept like a Good Diagram
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 traditional diagramming software. This is a relatively straightforward solution to a major hurdle in software teams, Knowledge Transfer and Documentation
A picture is worth a thousand words, a good diagram is worth a little more in my opinion, and there is no disputing that they are indeed very useful. Yet very few people use them, even fewer still do so, for documentation.
mermaid aims to change that.
## Creating and Maintaining Diagrams should not be an expensive and frustrating process.
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.
# Doc Rot and Dagrams
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.
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 traditional diagramming software. This is a relatively straightforward solution to a major hurdle in software teams,
# The primary objective of mermaid is to help in addressing the problem of Documentation Rot.
@@ -26,13 +40,6 @@ And they are rendered into this and made part of the documentation:
- The number of integrations that it has.
- It is a package that can be deployed to create
## Creating and Maintaining Diagrams should not be an expensive and frustrating process.
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.
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.
## Diagramming and charting is a gigantic waste of developer time, but not having diagrams ruins productivity.