DEV Community: Sébastien

"Diagram as code"

Sébastien — Fri, 01 Jan 2021 13:08:23 +0000

We have seen in the previous article that our primary driver is to keep the software documentation as near as possible to the developer, from a tool landscape and also from a process point of view. But if the documentation contains a couple of sentences, there are also many diagrams like the following.

source: https://c4model.com

a lovely picture from a whiteboard, or if the author took the time to transfer the drawing in a modeling tool, you could have something like that

source: https://sparxsystems.com

And in all the cases, it ends with a jpeg or png. Unfortunately, the diagram will evolve, and comparing two jpegs is not so easy :). Following the same approach, documentation as code, it was natural to move to diagrams as code. Simon Brown mentioned the growth of such an approach in this post. It was comforting to see that the way we were following since the last two years is taking speed.

To make our diagrams versionable and comparable, we use different plantuml dialects:

Plantuml for C4, yes we use C4 for the architecture documentation because we like the simplicity of the modeling and also the idea of navigability. We use then
Plantuml for AWS as our application is deployed on AWS, but you can also find versions for
Azure, or
GCP.

And with a simple code like that,

@startuml Basic Sample
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

Person(admin, "Administrator")
System_Boundary(c1, "Sample System") {
    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

we obtain

everything versionable

Now we have everything versionable. We can finally compare diagrams. As Simon Brown says, we are just diagraming, not modeling, and it is true. With the latest improvements of structurizr in the direction of diagram as code and cloud architecture, we can envisage a migration to such a modeling tool.

Our approach is strongly based on the idea of linking information allowing better navigation, and avoiding redundancy. We wanted to have the same experience at the diagram level, being able to jump into the documentation of the component or in the code directly. To this end, we extended:

jekyll-plantuml plugin to generate SVG with embed URLs
plantuml for C4 to naturally embed Url

@startuml
!include C4/C4_Container.puml
Person(admin, Administrator, "Alice", {{site.baseurl}}/alice/)
System_Boundary(c1, "Sample System") {
    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

Just to be convince, go to the following url and click on Alice or twitter.

To conclude, a diagram as code is a lightweight manner of documenting your architecture; you can focus on the content and not on tool usage. Give it a try, and if you combine it with jekyll, you have a fully navigable documentation.

Architecture documentation authoring and dissemination

Sébastien — Fri, 01 Jan 2021 13:07:58 +0000

This article will present how I envisage software documentation from the development, and tooling side.
First of all, architecture documentation is a critical asset as soon as you are more than two or three in the team. As Nikolay described in his article, the primary goals are knowledge sharing, communication, and analyses. But documenting the system's architecture is a difficult task. You always face the divergence between code and the documentation. Word/pdf documents or modelization files contain the documentation, making it challenging to find information and navigate between the artifacts.

For sure we can argue that each tool addresses different stakeholder needs. A modeling tool might be the preferred tool for a software architect, the repository selected by a developer, and a pdf for a management level. But we have to be honest; maintaining all is a pain. While setting up the documentation with my team, I asked the group: "what do we/they "feel" about the architecture and the documentation? It came out that:

Architecture is mostly from developers for developers
Architecture is living; it changes iterations after iterations
Code and architecture always diverge over time
Architecture is not a book you read from page one to the end
Architecture is not something to fulfill a process step, but it needs a process

Based on those thoughts, the concept of content as code was quite promising. Indeed the same rules should apply for the documentation as for the code. If the architecture is from developers for developers, why not use the same tool landscape (e.g., Git, vscode, or any IDE). Architecture is a living object like code, and it is also a critical asset we can apply the same processes (e.g., Quality gates within a CI, Merge Request…). Architecture and code always diverge over time; maybe putting them together might reduce the risk.
We ended with a classical developer tool landscape for the authoring part: Gitlab or any other source control system, markdown for the content, and Git for versioning.

With that solution, we were able to guarantee:

The versioning: the documentation evolves like the code following the same life cycle.
The quality, with merge requests like code
The traceability: with the ability to compare different versions as we are text-based.

The authoring aspect is addressed, but the reader's side was still not implemented. The team mentioned that you do not read architecture documentation like a book, starting from page one to the end. We prefer to navigate from a piece of information to another, from a high level of abstraction to an implementation detail. Fundamentally the reader wants to navigate! Which system has in his heart the navigability? The Web indeed! The documentation should be web-based. The web is navigable, links are the heart of the web, and with a single URL, you can dive into your documentation.

As depicted in the previous picture, we extended our tool landscape to generate a static website with Jekyll and the full integration into our CI/CD pipeline. Now the generated website is a kind of artifact like any dll or cloud deployment. It is synchronized with the code. It is readable to anyone who has the URL, and the unique tool needed by a reader is a web browser.

To conclude, in this article I presented how I tried with my team to address the authoring and dissemination of software architecture. Below some links to tools or concepts I used. In the next article, I will present how we handled the architecture diagrams.

Architecture documentation series

Sébastien — Fri, 01 Jan 2021 13:07:36 +0000

For a while, I found a list of articles from Nikolay Ashanin about software architect role and software architecture in general, and I encourage any software engineer to have a look at those. It gave me the idea to share my experience with a series of posts on how I envisage software architecture and, in particular, the documentation. Within the next articles, I will describe topics:

I hope you will enjoy that series, waiting for your comments.

DEV Community: Sébastien

"Diagram as code"

everything versionable

Architecture documentation authoring and dissemination

Links

Architecture documentation series