mermaid-js · knsv · Feb 27, 2020 · Feb 22, 2020 · Feb 22, 2020 · Feb 23, 2020
diff --git a/README.md b/README.md
@@ -9,7 +9,10 @@
 <!-- <Main description> -->
 __mermaid is a Javascript based diagramming and charting tool. It generates diagrams flowcharts and more, using markdown-inspired text for ease and speed.__
 
-Check out the list of [Integrations and Usages of Mermaid](./docs/integrations.md)
+Check out the list of [Integrations and Usages of Mermaid](https://github.com/mermaid-js/mermaid/blob/develop/docs/integrations.md)
+
+For more information and help in getting started, please view our [documentation](http://mermaid-js.github.io/mermaid/) and start simplifying yours. Alternatively, you can also play with our [live editor](https://mermaidjs.github.io/mermaid-live-editor/).
+<!-- </Main description> --> 
 
 :trophy: **Mermaid was nominated and won the [JS Open Source Awards (2019)](https://osawards.com/javascript/#nominees) in the category "The most exciting use of technology"!!! Thanks to all involved, people committing pull requests, people answering questions and special thanks to Tyler Long who is helping me maintain the project.**
 

diff --git a/docs/img/liveEditorOptions.png b/docs/img/liveEditorOptions.png
diff --git a/docs/liveEditorOptions.png b/docs/liveEditorOptions.png
diff --git a/docs/n00b-gettingStarted.md b/docs/n00b-gettingStarted.md
@@ -1,42 +1,46 @@
-# A more basic getting started
+# A basic mermaid User-Guide for Beginners
 
-Writing mermaid code is simple.
+Creating diagrams and charts, using mermaid code is simple.
 
-But how is the code turned into a diagram in a web page? To do this we need a mermaid renderer.
+But how is the code turned into a diagram in a web page? This is done with the use of a mermaid renderer.
 
-Thankfully the mermaid renderer is very accessible, in essence it is a javascript.
+Thankfully the mermaid renderer is very accessible, in essence it is a piece of javascript that can be called. 
 
-The requirement is on the part of the web browser. Modern web browsers, such as Firefox, Chrome and Safari, can render mermaid. But Internet Explorer cannot. The web browser also needs access to the online mermaid renderer which it downloads from https://cdn.jsdelivr.net/npm/mermaid
+Most widely used web browsers, such as Firefox, Chrome and Safari, can render mermaid, Internet Explorer however cannot. The web browser also needs access to the online mermaid renderer which it downloads from https://cdn.jsdelivr.net/npm/mermaid
 
-For an easy introduction, here follows three practical examples using:
-1. an online mermaid editor
-2. a mermaid plugin
-3. a generic web server of your choosing
+# For beginners, there are three relatively easy ways you can use mermaid:
+1. Using the mermaid [live editor](https://mermaid-js.github.io/mermaid-live-editor/)
+2. Using a mermaid plugin, such as that for Confluence or [Atom](https://atom.io/packages/atom-mermaid).
+3. Calling mermaid renderer with HTML, deployed in a friendly browser. 
 
-Following either of these examples, you can get started with converting your own mermaid code into web diagrams.
+# Following either of these examples, you can get started with creating your own diagrams using mermaid code.
 
-## the mermaid live editor
+## 1. The mermaid live editor:
 
-The quickest way to get started with mermaid is to visit [The mermaid live editor](https://mermaidjs.github.io/mermaid-live-editor).
+ A great way to get started with mermaid is to visit [The mermaid live editor](https://mermaidjs.github.io/mermaid-live-editor).
 
-In the `Code` section one can write or edit raw mermaid code, and instantly `Preview` the rendered result.
+In the `Code` section one can write or edit raw mermaid code, and instantly `Preview` the rendered result on the panel beside it.
 
-This is a great way to get started.
+![Flowchart](./img/n00b-liveEditor.png) 
 
-It is also the easiest way to develop diagrams, the code of which can be pasted straight into documentation.
 
-![Flowchart](./img/n00b-liveEditor.png)
+You can also copy the code from the code section and paste it into either a mermaid plugin or in inside an html file, which will be taught in numbers 2 and 3. 
+
+It is also an easier way to develop diagrams. You can also click "Copy Markdown" to copy the markdown code for the diagram, that can then be pasted directly into your documentation. 
+
+![Flowchart](./img/liveEditorOptions.png)
 
 The `Mermaid configuration` is for controlling mermaid behaviour. An easy introduction to mermaid configuration is found in the [Advanced usage](n00b-advanced.md) section. A complete configuration reference cataloguing default values is found on the [mermaidAPI](mermaidAPI.md) page.
 
 
-## mermaid using plugins
+## 2. Using mermaid plugins:
 
-Thanks to the growing popularity of mermaid, many plugins already exist which incorporate a mermaid renderer.
+Thanks to the growing popularity of mermaid, many plugins already exist which incorporate a mermaid renderer. An extensive list can be found [here](integrations.md).
 
-One example is the [Atlassian Confluence mermaid plugin](https://marketplace.atlassian.com/apps/1214124/mermaid-plugin-for-confluence?hosting=server&tab=overview)
+One example in the list is the [Atlassian Confluence mermaid plugin](https://marketplace.atlassian.com/apps/1214124/mermaid-plugin-for-confluence?hosting=server&tab=overview) 
 
 When the mermaid plugin is installed on a Confluence server, one can insert a mermaid object into any Confluence page.
+# Here is a step by step process for using the mermaid-Confluence plugin:
 
 ---
 
@@ -64,32 +68,40 @@ When the mermaid plugin is installed on a Confluence server, one can insert a me
 
 ---
 
-## mermaid using any web server (or just a browser)
+## 3. mermaid using any web server (or just a browser):
 
-This example can be used with any common web server. Apache, IIS, nginx, node express [...], you pick your favourite.
+This method can be used with any common web server. Apache, IIS, nginx, node express [...], you pick your favourite.
 
-We do not need to install anything on the server, apart from a normal file of html to be reached by a web browser (such as Firefox, Chrome, Safari, but not Internet Explorer). So if you want to really simplify things when testing this out, don't use a web server at all but just create the file locally and drag it into your browser window. It is the browser which does all the work of rendering mermaid!
+We do not need to install anything on the server, apart from a program (like Notepad++) that can generate an html file, which is then deployed by a web browser (such as Firefox, Chrome, Safari, but not Internet Explorer). 
 
-Through the html file, we give the web browser three instructions inside the html code it retrieves:
-1. a reference for fetching the online mermaid renderer, the renderer is just a javascript.
-2. the mermaid code we want to diagram.
-3. the `mermaid.initialize()` command to start the rendering process
+So if you want to really simplify things when testing this out, don't use a web server at all but just create the file locally and drag it into your browser window. It is the browser which does all the work of rendering mermaid!
 
-All this is done in the html `<body>` section of the web page.
+# Here are instructions for creating an html file with mermaid code: 
+# Note that all this is written in the html `<body>` section of the web page.
 
-This is what needs to go into the html file:
+When writing the html file, we give the web browser three instructions inside the html code:
+
+a. A reference for fetching the online mermaid renderer, which is written in Javascript.
+
+b. The mermaid code for the diagram we want to create.
 
+c. The `mermaid.initialize()` command to start the rendering process. 
+
+
+
+
+This is what needs to go into the html file:
 
 
-1. The reference to the mermaid renderer is done in a `<script src>` tag like so:
+# a. The reference to the mermaid renderer has to be contained in a `<script src>` tag like so:
 
 ```
 <body>
   <script src="https://cdn.jsdelivr.net/npm/mermaid@8.4.0/dist/mermaid.min.js"></script>
 </body>
 ```
 
-2. The embedded mermaid code is similarly placed in a `<div>` tag:
+# b. The embedded mermaid code is similarly placed inside a `<div>` tag:
 
 ```
 <body>
@@ -102,17 +114,18 @@ This is what needs to go into the html file:
   </div>
 </body>
 ```
+(take note that every mermaid chart/graph/diagram, has to have separate `<div>` tags.)
 
-3. When initializing mermaid using `mermaid.initialize()`, mermaid takes all the `<div class="mermaid">` tags it can find in the html body and starts to render them one by one. This is done like so:
+# c. When initializing mermaid using `mermaid.initialize()`, mermaid takes all the `<div class="mermaid">` tags it can find in the html body and starts to render them one by one. This is done like so:
 
 ```
 <body>
   <script>mermaid.initialize({startOnLoad:true});</script>
 </body>
 ```
 
-*Finally*
-4. Putting the three steps together is as simple as:
+# *Finally*
+# If the three steps mentioned are followed you will end up with something like this:
 ```
 <html>
   <body>
@@ -137,7 +150,7 @@ This is what needs to go into the html file:
   </body>
 </html>
 ```
-Save this to a html file and fetch it with a browser from the web server (or just drag it into your web browser window) and voila!
+# Save this to a html file and fetch it with a browser from the web server (or just drag it into your web browser window) and voila!
 
 ---
 

diff --git a/docs/n00b-overview.md b/docs/n00b-overview.md
@@ -1,8 +1,8 @@
 # Overview for n00bs
 
-As a sysadmin I frequently have to document things, including drawing stuff.
+mermaid is a tool that aims to make diagrams and flowcharts for documentation, easier. 
 
-Using mermaid, I can type this as a comment in a script:
+with mermaid, diagrams can be created through comments like this in a script:
 
 ```
 graph TD
@@ -11,17 +11,19 @@ B --> C[Server01]
 B --> D[Server02]
 ```
 
-And end up with this in the documentation:
+And they are rendered into this and made part of the documentation:
 
 ![Flowchart](./img/n00b-firstFlow.png)
 
-Most of the stuff I need to visualize can be scripted in a similar way, with a varitety of different symbols and chart types available. Since the diagram source is text based, it can be part of production scripts (and other pieces of code). So less time needs be spent on documenting as a separate task.
+Most of the similar visuals that you might need to create can be scripted in a similar way, with a varitety of different symbols and chart types available. 
+Since the diagram source is text based, it can be part of production scripts (and other pieces of code). So less time needs be spent on documenting as a separate task.
 
-Comparing with Visio and similar applications, mermaid is a really fast way to create good visualizations. This is especially apparent when editing a complex visualisation, this could take me hours in a desktop application but takes minutes (or even less if generation has been scripted) with mermaid.
-
-With mermaid I can spend a fraction of the time I normally would spend, and instead automate the diagram generation and end up saving even more time. I love it!
+Comparing with Visio and similar applications, mermaid is a really fast way to create good visualizations. This is especially apparent when editing a complex visualisations, a process that usually takes hours in a desktop application, but only takes minutes (or even less if generation has been scripted) with mermaid.
 
+mermaid can potentially cut down the amount of time and effort spent on the process of creating diagrams, to a fraction of what you usually put in.  
 
 However, a lot of the mermaid documentation is geared to professional frontend developers, presuming a skill set which I simply do not have.
 
-I needed a really basic instruction. And here it is.
+If you need some basic instructions and introductions, here are a few good places to start:
+
+For information on how to use mermaid, click [here](https://mermaid-js.github.io/mermaid/#/n00b-gettingStarted), or you can try out the mermaid [live editor](https://mermaid-js.github.io/mermaid-live-editor/), alternatively, you could also view the [integrations and uses](https://github.com/mermaid-js/mermaid/blob/develop/docs/integrations.md) for mermaid.