adding pictures

using c# coloring, because plantuml is not possible at github adding layout options adding overview
khvysofq · Sep 5, 2018 · aafe76f · aafe76f
1 parent a234d78
commit aafe76f
Showing 1 changed file with 109 additions and 36 deletions.
diff --git a/README.md b/README.md
@@ -4,50 +4,36 @@ C4-PlantUML combines the benefits of [PlantUML](http://en.plantuml.com/) and the
 
 C4-PlantUML includes macros, stereotypes, and other goodies (like VSCode Snippets) for creating C4 diagrams with PlantUML.
 
-## Background
-
-[PlantUML](http://en.plantuml.com/) is an open source project that allows you to create UML diagrams.
-Diagrams are defined using a simple and intuitive language.
-Images can be generated in PNG, in SVG or in LaTeX format.
-
-PlantUML was created to allow the drawing of UML diagrams, using a simple and human readable text description.
-Because it does not prevent you from drawing inconsistent diagrams, it is a drawing tool and not a modeling tool.
-It is the most used text-based diagram drawing tool with [extensive support into wikis and forums, text editors and IDEs, use by different programming languages and documentation generators](http://en.plantuml.com/running).
-
-The [C4 model](https://c4model.com/) for software architecture is an "abstraction-first" approach to diagramming, based upon abstractions that reflect how software architects and developers think about and build software.
-The small set of abstractions and diagram types makes the C4 model easy to learn and use.
-C4 stands for context, containers, components, and code — a set of hierarchical diagrams that you can use to describe your software architecture at different zoom levels, each useful for different audiences.
-
-The C4 model was created as a way to help software development teams describe and communicate software architecture, both during up-front design sessions and when retrospectively documenting an existing codebase.
-
-More information can be found here:
-
-* [The C4 model for software architecture](https://c4model.com/)
-* [REAL WORLD PlantUML - Sample Gallery](https://real-world-plantuml.com/)
-* [Visualising and documenting software architecture cheat sheets](http://www.codingthearchitecture.com/2017/04/27/visualising_and_documenting_software_architecture_cheat_sheets.html)
-* [PlantUML and Structurizr - Create models not diagrams](http://www.codingthearchitecture.com/2016/12/08/plantuml_and_structurizr.html)
+* [Getting Started](#getting-started)
+* [Snippets for Visual Studio Code](#snipptes-for-visual-studio-code)
+* [Layout Options](#layout-options)
+  * [LAYOUT_TOP_DOWN or LAYOUT_LEFT_RIGHT](#layout_top_down-or-layout_left_right)
+  * [LAYOUT_WITH_LEGEND](#layout_with_legend)
+  * [LAYOUT_AS_SKETCH](#layout_as_sketch)
+* [Advanced Samples](#advanced-samples)
+* [Background](#background)
 
 ## Getting Started
 
 At the top of your C4 PlantUML `.puml` file, you need to include the `C4_Container.puml` file found in the `root` of this repo.
 
 To be independent of any internet connectifity, you can also download `C4_Container.puml` and reference it locally with
 
-```plantuml
+```c#
 !include path/to/C4_Container.puml
 ```
 
 If you want to use the always up-to-date version in this repo, use the following:
 
-```plantuml
+```c#
 !includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml
 ```
 
 After you have inlcluded `C4_Container.puml` you can use the defined macro definitions for the C4 elements: `Person`, `System`, `Container`, `Relationship`.
 
-```plantuml
-@startuml Basic Sample
-!include C4_Container.puml
+```csharp
+@startuml C4_Elements
+!includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml
 
 Person(personAlias, "Label", "Optional Description")
 Container(containerAlias, "Label", "Technology", "Optional Description")
@@ -57,13 +43,15 @@ Rel(personAlias, containerAlias, "Label", "Optional Technology")
 @enduml
 ```
 
+![C4_Elements](http://www.plantuml.com/plantuml/png/ZL31IWCn4Bq7yW_hdbQecqjFdYhRtgejLSybpGxTm6GICXDA_zwmO554yVJU36_UUyoAnMOf0PjXUTmW121XhUuyEImZb8pD99BuqPXiB_tPorHEXI6xI5ArlOl17BopUOml7XAW6POFUxGaxyzR4omBvBew3bLlFK7kKqtJIgizP8xKfHcUq5jUDEtMdW3RIdP9V2IBpHhOPJzFxRrMDv_EVR8Vjs_W9eeOpzU_d5wljLleU8P_vsjr0FnU-lSYDvClZQh72cYiJ_W0 "C4_Elements")
+
 In addition to this, it is also possible to define a system boundary.
 
 Take a look a look at the following sample of a C4 Container Diagram:
 
-```plantuml
+```csharp
 @startuml Basic Sample
-!include C4_Container.puml
+!includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml
 
 Person(admin, "Administrator")
 package "Sample System" <<boundary>> as c1 {
@@ -76,7 +64,9 @@ Rel(web_app, twitter, "Gets tweets from", "HTTPS")
 @enduml
 ```
 
-## Snipptes for Visual Studio Code
+![Basic Sample](http://www.plantuml.com/plantuml/png/LL1DIyD04Bq7yX_6UAbG4ogUf9J687gmfJIf7iis6Tl5_M9tGYZYVtUMQejx6PZtvdtiF93mr6i5ZoB85cgXdS8qkPAcLNs7lLTm87BXeIYy6FAzf4E_wmFwrXf2GtbhTR6MhV2TNKfqg8hg_dQbXA7DuhNG8X1wNcqhvWjfqEUExT8aJLReWpKZqMbfnf2LSSf0Nf3rsKsQED5-YZr2TWe5zP6rT0RJwSxsfXF-E9k12D1Eu2jDWD_POpJWRYkSOzbtt47fdEA89At9U5LTZw6iL_dogU4JZt2NJs3nLaMiLCeE0MB306I1wpd15DqhaZ55CqZYIa1IesAl4AD-fyaftOXEC2lz4YES9cjKVqKlqJQ1htc-DCsgZhp8EiCNfMSapZ9W71_UwdytSpGTV-WF "Basic Sample")
+
+## Snippets for Visual Studio Code
 
 Lorem
 
@@ -94,9 +84,9 @@ For this reason, C4-PlantUML also comes with some layout options.
 
 With the two macros `LAYOUT_TOP_DOWN` and `LAYOUT_LEFT_RIGHT` it is possible to easily change the flow visualization of the diagram. `LAYOUT_TOP_DOWN` is the default.
 
-```plantuml
-@startuml Basic Sample
-!include C4_Container.puml
+```csharp
+@startuml LAYOUT_TOP_DOWN Sample
+!includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml
 
 ' Not needed because this is the default
 LAYOUT_TOP_DOWN
@@ -112,11 +102,13 @@ Rel(web_app, twitter, "Gets tweets from", "HTTPS")
 @enduml
 ```
 
+![LAYOUT_TOP_DOWN Sample](http://www.plantuml.com/plantuml/png/NL5TQzj047mNw3zib8Swa4gaz2cO4E66zY6nHImtzCcifBLzvBwuMo5Cw7_l7cuIakDWuMPsTcRlDZ867es6-_hFQjDksrMp_R5wMi8QZTUKPsVAzdeSQ0mQ3im-NbTLmAdSApwCtHWfzCuoMIvxPwf7rMCOt5AH9rqjldzjD5hUFDnN1YDJaAVjGlYeB8NIo-0yoxCli7GCbcYW0JhgKMI13og2N3uG3BJ3KNEUVNAPcXiAqTaP3aRPIoZgL5NaWEn2SP5d7ljdt1CKfqImFeeHKy1ythdH3XYEDpU04VehUCapaFDcS3PHjqNlHVQ9EgYzrvAFbRE5F2tEBw5UD-NohfMMGF2jl8A7tuk4rLgxAK9QZoHm8BlnA1GZALHoqKwAPH_0of2MMJ5P_Pjd9tSpFi6Yz9-Ou3nx9FqQzDtQ9agtr5zjswmJBx7Uu7UbdyJYPQ9KTi6P3pstP0VvZNy0 "LAYOUT_TOP_DOWN Sample")
+
 Using `LAYOUT_LEFT_RIGHT`
 
-```plantuml
-@startuml Basic Sample
-!include C4_Container.puml
+```csharp
+@startuml LAYOUT_LEFT_RIGHT Sample
+!includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml
 
 LAYOUT_LEFT_RIGHT
 
@@ -131,10 +123,91 @@ Rel(web_app, twitter, "Gets tweets from", "HTTPS")
 @enduml
 ```
 
+![LAYOUT_LEFT_RIGHT Sample](http://www.plantuml.com/plantuml/png/PL1TIyD047mFv3-iyQL2JQZu94KCeNv0rTAcYa_bagnwU5_SRGX5_E_kKMqHxsLWPtPdvgu22K-zLZ0lNnxNzMO-kwutoxkRsnfMGZk5QN8aJQlw3dklu9t8XOkYy6B8toIzzqqVqBVM41hAMwkBfMo5x-o3H8UggCvF5qeOMj_F2oq2eUVHfcAza0PzxjWwJTBadtiSBj07QqQYqzAC8IiZoa1UaFNPIPeuqNw8DuHibnHMMpRG6KodZUrD9_psyX94W7O2dsa2_FR6em6RZN2EppvZ0wLpYdEJj2RZKNKyXdAro1zcDQzuXBDy0lTFLUHAfUmG8DOEG1QuinCiqRqY6LFKWoJk2IGrAlOACUfNckpIZMX7ywKVOQJJP8dgj-WXsZhmDkDjNIzMKHTLU_fmwGQ9immOuTLR_MVd2at7l_mD "LAYOUT_LEFT_RIGHT Sample")
+
 ### LAYOUT_WITH_LEGEND
 
 Colors can help to add additional information or simply to make the diagram more aesthetically pleasing.
+It can also help to save some space.
+
+All of that is the reason, C4-PlantUML uses colors and prefer also to enable a layout without `<<stereotypes>>` and with a legend.
+This can be enabled with `LAYOUT_WITH_LEGEND`.
+
+```csharp
+@startuml LAYOUT_WITH_LEGEND Sample
+!includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml
 
+LAYOUT_WITH_LEGEND
+
+Person(admin, "Administrator")
+package "Sample System" <<boundary>> as c1 {
+    Container(web_app, "Web Application", "C#, ASP.NET Core 2.1 MVC", "Allows users to compare multiple Twitter timelines")
+}
+System(twitter, "Twitter")
+
+Rel(admin, web_app, "Uses", "HTTPS")
+Rel(web_app, twitter, "Gets tweets from", "HTTPS")
+@enduml
+```
+
+![LAYOUT_WITH_LEGEND Sample](http://www.plantuml.com/plantuml/png/PL1TIyD047mFv3-iyQL2JQZu94KCjLYXrj2aYa_bcgpryBwusn14_E_kKJyGxsLWPtPdvgu22K-zLh0id-utpVRnjbbib_ER-UeQQg6TmZGvagPLVOUzL_12vC95KNWnv7j9B_sk3-XRQmWDvQtLnLgsmdTs9T6XAcRdfvKIXZPtoqABGEXvj9snNaY3FdVidIPfyjy-JYlqmPgHwBGqOyZAY3AG5sHzTf8cJhIlOe-G7Q92_SOEEeFfT6Txqmd_Tda98a0xWVSq0Nu_pgC1TrlX79zzn1sKpYaEJjAQZ4Upup6KTPMlvWslU8IpV09t3xF8bKhP8K3i7O0iS6adMA9xHJAcQ0P9N1H8QbJi5MBKZpGvf1lHWUPBNy98fyaQrNVHtsYRmDkCYwQfwgYBgX_wzz8D4cSPCCApj_hFpXMQZh_v4m00 "LAYOUT_WITH_LEGEND Sample")
+
+### LAYOUT_AS_SKETCH
+
+C4-PlantUML can be especially helpful during up-front design sessions.
+One thing which is often ignored is the fact, that these software architecture sketches are just sketches.
+
+Without any proof
+
+* if they are technically possible
+* if they can fullfil all requirements
+* if they keep what they promise
+
+More often these sketches are used by many people as facts and are manifested into their documentations.
+With `LAYOUT_AS_SKETCH` you can make a difference.
+
+```csharp
+@startuml LAYOUT_AS_SKETCH Sample
+!includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/master/C4_Container.puml
+
+LAYOUT_AS_SKETCH
+
+Person(admin, "Administrator")
+package "Sample System" <<boundary>> as c1 {
+    Container(web_app, "Web Application", "C#, ASP.NET Core 2.1 MVC", "Allows users to compare multiple Twitter timelines")
+}
+System(twitter, "Twitter")
+
+Rel(admin, web_app, "Uses", "HTTPS")
+Rel(web_app, twitter, "Gets tweets from", "HTTPS")
+@enduml
+```
+
+![LAYOUT_AS_SKETCH Sample](http://www.plantuml.com/plantuml/png/NL1DIyD04Bq7yX_6UAbG4nHFKaf340MhbYPLF8LjCkhYVh4x8OZutvsbsg9x6PZtvdti8f3mD6W5o_BvOTEqPTtMjrTDTGErq4vXcXn9qwcXny4hU2DouR8el1ZpLqblmtO8w3jh20tbdTN5MdR2z_PUeaDLL1UdAoKCRUwMXHQ1qFEghPWlf46VEtPEapJvRnvtA_J1cedejJHJoCeuPI0loFhi94sSwDx5AqAs2mhr1-lh36QphHrCB_p7V0uYG7S6dsa2_FQ-an6thN2EPPzm2wLpYcEJj2RZLNKyXR9UvVTN3PzuXFFy3EuUguYLIjanG6mTW2nmPIUOeWT5CgPeHabS4qXgLEmLOjIlDDcbcz0EPgKVOeJJP8tgj-WXsYRmDS-RfbdLaHTPU_YWT8t4MKQCuyLR_UTcWQRdJ_u6 "LAYOUT_AS_SKETCH Sample")
 
 ## Advanced Samples
 
+// TODO
+
+## Background
+
+[PlantUML](http://en.plantuml.com/) is an open source project that allows you to create UML diagrams.
+Diagrams are defined using a simple and intuitive language.
+Images can be generated in PNG, in SVG or in LaTeX format.
+
+PlantUML was created to allow the drawing of UML diagrams, using a simple and human readable text description.
+Because it does not prevent you from drawing inconsistent diagrams, it is a drawing tool and not a modeling tool.
+It is the most used text-based diagram drawing tool with [extensive support into wikis and forums, text editors and IDEs, use by different programming languages and documentation generators](http://en.plantuml.com/running).
+
+The [C4 model](https://c4model.com/) for software architecture is an "abstraction-first" approach to diagramming, based upon abstractions that reflect how software architects and developers think about and build software.
+The small set of abstractions and diagram types makes the C4 model easy to learn and use.
+C4 stands for context, containers, components, and code — a set of hierarchical diagrams that you can use to describe your software architecture at different zoom levels, each useful for different audiences.
+
+The C4 model was created as a way to help software development teams describe and communicate software architecture, both during up-front design sessions and when retrospectively documenting an existing codebase.
+
+More information can be found here:
+
+* [The C4 model for software architecture](https://c4model.com/)
+* [REAL WORLD PlantUML - Sample Gallery](https://real-world-plantuml.com/)
+* [Visualising and documenting software architecture cheat sheets](http://www.codingthearchitecture.com/2017/04/27/visualising_and_documenting_software_architecture_cheat_sheets.html)
+* [PlantUML and Structurizr - Create models not diagrams](http://www.codingthearchitecture.com/2016/12/08/plantuml_and_structurizr.html)