131–140 of 159 posts
I love architecture docs, but find they're often written using a funny process: 1. Spend a long time writing the doc. 2. Wait for a person to chance upon it. 3. Hope you anticipated their questions. It seems like the most important thing a person can do is reverse this: 1. Say who the doc is for. 2. Find that person. Ask them to try a lil contribution. 3. Frantically write / revise the doc. IMO it's a lot like creati…
As someone who is in week two of spooling up on a multi-million-line codebase where most of the original authors have moved on to other projects, please, I beg you to heed this advice. I spend the vast majority of my time figuring out where a change needs to happen. The patches themselves are no more than 10% of the work. (The other significant factor is running tests.)
It's called job security bub. I'm not going to write out everything you need to know. Hire an expert and whatever time it takes him to figure out is how much it's going to cost you to churn through employees. Don't like it? Be a better employer so your employees don't leave.
Earlier quoted context omitted.
I disagree with this characterization. ARCHITECTURE.md is specifically engineered to be low churn, so in this respect it is meaningfully different from other “keep docs” advise. In practice, I personally didn’t find it difficult to maintain half-decent ARCHITECTURE.md, and I am not at all good with keeping the docs otherwise.
> specifically engineered to be low churn This is not actually possible. You're kidding yourself if you think such a document is "future proof."
Earlier quoted context omitted.
I disagree with this characterization. ARCHITECTURE.md is specifically engineered to be low churn, so in this respect it is meaningfully different from other “keep docs” advise. In practice, I personally didn’t find it difficult to maintain half-decent ARCHITECTURE.md, and I am not at all good with keeping the docs otherwise.
> specifically engineered to be low churn This is not actually possible. You're kidding yourself if you think such a document is "future proof."
As someone who is in week two of spooling up on a multi-million-line codebase where most of the original authors have moved on to other projects, please, I beg you to heed this advice. I spend the vast majority of my time figuring out where a change needs to happen. The patches themselves are no more than 10% of the work. (The other significant factor is running tests.)
It's called job security bub. I'm not going to write out everything you need to know. Hire an expert and whatever time it takes him to figure out is how much it's going to cost you to churn through employees. Don't like it? Be a better employer so your employees don't leave.
There is an important aspect of writing architectural docs (or any docs for that matter) that is often overlooked. Write simply and clearly. Too much verbosity and detail is difficult to follow. That's what the code is for. It is almost a superpower to be able to write succinctly and clearly. This isn't some contest to showoff your deep knowledge of a particular niche. I've seen developers get 'nerdy' with their docs…
One trick here is to keep in the source, every sentence on a separate line. That way, it's hard to miss complicated sentences. As a bonus, docs become easier to diff.
rust-analyzer does this: https://raw.githubusercontent.com/rust-analyzer/rust-analyze...
My approach: 1. put a one line comment at the top of each code file. 2. The build extracts that comment and dynamically updates a readme.md for the directory that describes each code file. 3. The build also produces a master document that includes the same summaries in a single document. This provides a light indication of what each code file is and how they are organized into directories. It doesn’t provide any indi…
Do you have an example repo?
Earlier quoted context omitted.
Thanks for putting that out there. It's super interesting to see what we consider architecture to be. Your approach appears operational, focused on how the completed system functions, i.e. getting a new team member up to speed on the codebase. Typically I try to start with tiers (1, 2, n-tiers...?) that show how the system might be deployed. I then list list layers (user/facade/business/data), interfaces between thes…
Your approach seems like it would reduce the likelihood of implementation-time surprises. It also seems like different sections would satisfy different audiences. Do you have any book recommendations?
https://www.wittenburg.co.uk/Work/Books.aspx
The one that made the biggest impact on my approach to architecture is "Designing Solutions for Your Business Problems: A Structured Process for Managers and Consultants" by Betty Vandenbosch.
The one that made the biggest impact on me in ever is "Wicked Problems, Righteous Solutions" by Peter DeGrace and Leslie Hulet Stahl. Lots of forehead slapping and kicking myself ensued. Even more applicable today than it was in 1990 when written.
"Peopleware: Productive Projects and Teams" by Tom DeMarco and Timothy Lister comes as a very close second.
Not directly architecture or technology-related is "The Story Factor by Anette Simmons". It... changes you. Really useful for technical writing.
Earlier quoted context omitted.
Agree! I gave that feedback many times, who cares about commit message? I want documentation here! I think Github should really start taking a stance on convention, and come up with project structure conventions that would help project navigation. For example, youtube does that with chapters in videos, if you write a description with timestamps it will display these chapters in the timeline of the video[1]. IMO Githu…
This makes me think we should be able to put something like a standard tag for a 1-line summary (maybe embedded in some markdown in a comment) in a fashion the VCS's can detect & extract and then render in their UXs. e.g. something very simple would probably work like the first line found that matches something like: [Ignore_Non_Words]Summary[IgnorePunctuation&Spaces](Capture)
It would encourage people to write folder-level readmes if nothing else.
Earlier quoted context omitted.
Critical outcomes are defined by quality objectives (I mentioned some above, others are reliability, robustness and portability). People don't consider using my project. There's a client with a business problem, there's a vendor who solves problems for clients. The vendor produces an architecture document that describes how technology will achieve a solution †. There is no noping the fuck out, as this is a hospital a…
> Or an electoral district asking you to merge three emergency response systems into one. Or Nokia asking you to tariff calls going through a switch in real time. I’m well aware of what it is. I’ve been on real time telecom stuff (your last example) and know for a fact that engineers nope the fuck out of these huge ass architecture documents that include stakeholders, change control, etc. Inevitably there is some kin…
OMG you worked on that? The blame for this one (and Universal Credit) sits with GDS. Their approach at the time was agile or die, and then try to develop an enterprise system like they did the Guardian's CMS (GDS was staffed initally by ex-Guardian devs).
I had the misfortune of reviewing their Government Gateway replacement, which at the time focused singularly on identity federation. GDS was hugely anti-Microsoft, who built the Govrernment Gateway. And so they chose the SAML protocol over the incumbent ADFS, breaking every dependency.
GDS was way out of its league. An inexperienced 25y/o will draft exactly the kind of architecture document you describe.
I feel for you, and I now understand the cyncism.