Where I work now, it's a shitshow. To a (technical) outsider who wasn't with the company when they built everything, the original requirements and constraints are not obvious. The solution was lazily built in an ad-hoc fashion, so requirements continuously emerged out of the need to work around the failings of some other foundational system that was badly implemented. Suddenly you're being asked for a zero latency relational database with 100% uptime and infinite storage, and you ask "why?". Somebody points to the fractal-like complexity of the existing system and says, "It's the only way to make it work properly". You ask for diagrams, design docs or operational docs. Someone hand-waves at the fractal monolith and says "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!
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.
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.
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.
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.
This is indeed a big challenge for seniors hires. They are expected to understand the domain, product, and business context to create impact in little time.
I experienced this myself twice, failed miserably once and just about hung on second time. I've also seen quite a few senior ICs being let go within 4-6 months because they just couldn't get their head around the mess.
The obvious response of "document everything" hasn't been useful where I worked. Either company didn't embrace them or they got out of date in short time. I just don't know how to tackle it beyond putting in hard grunt work to understand the system.
> I just don't know how to tackle it beyond putting in hard grunt work to understand the system.
My team are simply replacing large chunks of infrastructure with properly built & documented infrastructure as code. If anyone has a problem, we're asking for a bake-off between this (sensible stuff) and that (wherever-the-hell mess you've got there).
