Ex: I work in the energy sector at the moment; because their gas/electricity usage varies across the year, there's a system in place where they pay a fixed amount per month, then they pay or get paid back the difference by the end of a contract year.
It's in the energy company's best interest that the monthly amount they pay is on par. The process to adjust this monthly amount is administrative, but in addition to that there's a huge stack of things to deal with across platforms; website, apps, back-end, support, support user interface, etc etc etc.
All the processes involved in just this aspect of the company need to be documented and drawn out as well, because else it has to be figured out from code or various people that happen to have it in their head. That's where a lot of the meeting culture comes from, because there's no one person in charge of this process, and the ones that know enough don't get together to write it down (and then maintain that documentation).
The reason why is because it allows a diagram to support more of the cross-cutting concerns by drawing a red arrow or a green arrow through things instead of a blue one.
It's a big moment in my realizations around technical communication. Like, I already knew this stuff mattered, but it's made more concrete when you can look at a diagram and the holistic whole helps you make more sense of things even if the details aren't right yet.
I use an airplane analogy (different order than your three above):
1. "Congratulations on purchasing your 747"
2. "This is how you replace the auxiliary power unit"
3. "This is how you survive the engine catching fire"
Edit: word choice
If I'm properly getting your point, you think there should be user manuals, administration and maintenance procedures, and architecture specifications and/or decision records.
Except...
> User docs are simple.
User docs are NOT simple. You have to put yourself into the mind of someone who is going to use your software to solve a problem which they have. That's never easy and it gets really hard, really fast, as the software grows in complexity or as your audience gets wider.A complete reference of how to do A, ..., X, Y, and Z but lacking conceptual context could actually be detrimental to a customer's productivity and the ultimate success of your product.
Providing accessible conceptual guidance can be very challenging depending on the domain.
If the user needs complex docs to perform a complex task - that's 100% OK. Just don't write complex content when a simple (or direct) explanation will do.
My (perhaps overly simplistic) take would be that we should take the thinking we use on the product itself (Who's going to use it? In what context? What would they already know? And so on), and apply and adapt it to the docs as we would any other product.
mostly the same but some additional information for people who are interested
Technical writers train specifically to communicate complex technical topics to readers, and it's not an easy job. It requires understanding your readers, what kind of backgrounds they have, and what are they trying to achieve. This becomes especially important for documentation that is meant for your customers, where very real revenue depends on the quality of your docs.
I'm a bit biased since I'm the founder of a documentation startup [0], but tools also do play a big part. Devs often tend to enjoy writing something Markdown next to their code than going to an old wiki like Confluence that's disconnected from the engineering cycle. Choosing the right tool lowers the barrier to keeping the docs up to date.
Great phrase!
To me, there are three places that dev-generated documentation can live:
1. The code
2. The issue tracker
3. The version control system
A small amount of exceptionally useful and frequently referred to documentation like the process for setting up a new dev environment or some complex support task can live elsewhere.
Otherwise, I think the top down imposition of a documentation culture is unlikely to succeed.
The real secret to getting a team that has a shared understanding of the system, the business, and each other is to retain your developers. A team that's been together for five years has superpowers no amount of documentation can replicate.
You should write three types of documentation. One for users, one for admins and one about architecture.
User docs are simple. How do I use it. What are the API calls, etc. Admin docs are about how to install/break-fix/troubleshoot issues that are beyond user interaction. Architecture is how the system is constructed, why certain tech was chosen, etc.
There's nothing that makes documentation more useless than when you're trying to do something like install the software but you have to dig thru piles of docs about why Postgres was chosen over MySQL. If your users or admins cant find the info they need quickly, they'll soon discard the documentation and user/system ops will go back to word of mouth knowledgeable.
I really think good companies focus on this and those who are successful really shine.