<p>I'd recommend starting with <a href="https://agilemodeling.com/" rel="nofollow noreferrer">the principles and practices of Agile Modeling</a>.</p>
<p>The diagramming and modeling notations are going to vary by team. There's no reason why teams couldn't use SysML or UML, and the use of a standard notation is often seen as a good practice. Regardless of the notation(s) used, in my experience, less formal approaches are used, such as using the language <a href="https://martinfowler.com/bliki/UmlAsSketch.html" rel="nofollow noreferrer">as a sketch</a> or <a href="https://martinfowler.com/bliki/UmlAsNotes.html" rel="nofollow noreferrer">as notes</a>.</p>
<p>Using docs-as-code or diagrams-as-code approaches can be beneficial because the documentation can be stored alongside the code. It becomes easy to see the history of changes to both code and documentation and understand if one is changing without the other. However, not all stakeholders are as comfortable working with diagrams expressed as code, so the maintenance may fall to the developers rather than being collaborative.</p>
<p>It comes down to having just enough documentation to understand the problem, align on a solution, and enable people to understand the system in the future to continue to iterate. The implementation of this documentation needs to be light enough that it's easy to maintain or discard when it no longer becomes necessary. Like the rest of the work, building and maintaining documentation and models is iterative and incremental.</p>

CC BY-SA 4.0
2024-12-05T18:02:21.020Z
2024-12-05T18:02:21.020Z
Thomas Owens
<p>I try searching for things like documentation, modeling, SysML, or UML in the context of DevOps and I have not gotten much information if at all. I finished reading the Phoenix Project and have the DevOps handbook and there is no mention of anything. Looking at the AF Software Factories info sites has no information. Not even Will Ropers' papers on Bending the Spoon mention it. Although there is a mention of MBSE.one.</p>
<p>I had the impression that at least &quot;docs-as-code&quot; would appear since that what I have seen in a DevOps environment where text was in markdown and UML was in PlantUML. This is because one can check in the entire configuration script, source files and everything else needed to &quot;build&quot; the documentation in CI/CD as was suggested in the DevOps handbook.</p>
<p>How are agile organizations with rapid feedback loops doing documentation these days? I'd like to get up to date on the latest. I got a feeling that I am just mixing waterfall and agile and not getting anywhere with design documentation.</p>

<devsecops><software-engineering><design>
How is design documentation or modeling done in a DevOps environment?
Passeris
# How is design documentation or modeling done in a DevOps environment?

(Asked by: username_0 on 2024-12-05)

I try searching for things like documentation, modeling, SysML, or UML in the context of DevOps and I have not gotten much information if at all. I finished reading the Phoenix Project and have the DevOps handbook and there is no mention of anything. Looking at the AF Software Factories info sites has no information. Not even Will Ropers' papers on Bending the Spoon mention it. Although there is a mention of MBSE.one.

I had the impression that at least "docs-as-code" would appear since that what I have seen in a DevOps environment where text was in markdown and UML was in PlantUML. This is because one can check in the entire configuration script, source files and everything else needed to "build" the documentation in CI/CD as was suggested in the DevOps handbook.

How are agile organizations with rapid feedback loops doing documentation these days? I'd like to get up to date on the latest. I got a feeling that I am just mixing waterfall and agile and not getting anywhere with design documentation.

**Tags:** devsecops, software-engineering, design


---

## 1 answers

### Answer by username_1 on 2024-12-05. Score: 0 | Accepted answer

I'd recommend starting with [the principles and practices of Agile Modeling](https://agilemodeling.com/).

The diagramming and modeling notations are going to vary by team. There's no reason why teams couldn't use SysML or UML, and the use of a standard notation is often seen as a good practice. Regardless of the notation(s) used, in my experience, less formal approaches are used, such as using the language [as a sketch](https://martinfowler.com/bliki/UmlAsSketch.html) or [as notes](https://martinfowler.com/bliki/UmlAsNotes.html).

Using docs-as-code or diagrams-as-code approaches can be beneficial because the documentation can be stored alongside the code. It becomes easy to see the history of changes to both code and documentation and understand if one is changing without the other. However, not all stakeholders are as comfortable working with diagrams expressed as code, so the maintenance may fall to the developers rather than being collaborative.

It comes down to having just enough documentation to understand the problem, align on a solution, and enable people to understand the system in the future to continue to iterate. The implementation of this documentation needs to be light enough that it's easy to maintain or discard when it no longer becomes necessary. Like the rest of the work, building and maintaining documentation and models is iterative and incremental.


---

