From aafe76fd355bd0a6f3ece9f01e1fd7ae9b8133a7 Mon Sep 17 00:00:00 2001 From: Ricardo Niepel Date: Wed, 5 Sep 2018 20:12:31 +0200 Subject: [PATCH] adding pictures using c# coloring, because plantuml is not possible at github adding layout options adding overview --- README.md | 145 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 109 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index a9b4832..7d794d9 100644 --- a/README.md +++ b/README.md @@ -4,28 +4,14 @@ 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 @@ -33,21 +19,21 @@ At the top of your C4 PlantUML `.puml` file, you need to include the `C4_Contain 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" <> 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 `<>` 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" <> 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" <> 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) \ No newline at end of file