[Multicomp]

> Documentation as code, man

In my list of mean things I'm going to insist on should I ever go crazy and start my own company, documentation will be just as if not more incentivized than the actual code.

I want design diagrams, users lists, documented decisions on how backups are expected to happen, how this is expected to scale, why we went with X pattern instead of Y, who asked for a given feature, then as a last measure start doing the brittle document bits like API reference n such.

The code has its own inertia and desirability, but if you don't push docs, they are looked down on even though they have proven value.

What are we, scientists building and designing a new system or children slapping mud into a play dough concrete mixer and moving on to our next mud pie? Write it down Mr supposed professional!

[throwawayboise]

One of the things that has struck me as ironic for people who like to call themselves "engineers" is how resistant to documentation some software developers are. I understand and have experienced all the problems with documentation taking time and how easily it can get out of date, but when I look at what other engineers do when they need to modify a building or structure, they immediately go to the blueprints that tell them how the building is put together, where the structural support is, where the wiring and plumbing is, etc.

I guess those can just as easily suffer getting out of date, not updated with small changes, etc. but at least they provide a picture of how the thing was built in the first place, a picture that is still helpful for understanding.

[nicklarsennz]

I've found Lightweight Architecture Decision Records (as markdown docs in a repo with the code, or wherever makes sense) to explain the current landscape, options, decision, and foreseeable consequences. Keeping it really light makes it tolerable for people who don't like to write docs, though does need the team to insist on the doc for anything non trivial.

I also like using the Draw.io vscode extension to draw diagrams without having to export into a separate file or copy into the repo.

[RSHEPP]

I push for plantuml sequence diagrams for almost any new feature. Keep the files in SCC and can review with the MR.

Most engineers find them useful and not too much of a headache to write.

[Wistar]

Back when I did these sorts of doc tasks for a prototyping team, I used to create BUML* using Visio. It was kind of hard but nowhere near as hard as using Rational's offering. The dev team liked and used them. I like the looks of PlantUML. Thanks for posting about it.

* Bastardized Universal Markup Language.

[euroderf]

Careful with that wishlist. Design diagrams can quickly go out of sync with reality, and with no loop of responsibility to keep them up to date. In other words, brittle. Some artifacts are relatively timeless (like "Why we decided in 2018 to do X") but others are not.