Writing documents is so passé nowadays.
The (software development) industry has removed this activity from typical software crafts(wo)men agendas nearly completely. The longest written forms we have to deal with are usually: commit messages, user stories in Jira, integration test specifications in some Cucumber offspring, and PR comments. In many organizations, writing is fully consciously "outsourced" to non-techie roles like Business Analysts or ... even Scrum Masters (if they have any, are SMs still a thing?).
To be frank, IMHO very few (developers) miss writing at all.
Some scratching on the whiteboard or a sheet of paper usually suffices. And no-one condemns us for that because the common perception on writing documents is unequivocally negative:
- it's expensive (absorbs the people with the most valued skills on board) and slows things down
- it collides with a proactive "just do it" attitude
- debates on the written texts tend to end inconclusive, burdened with the weight of repetitions, ever-spawning sub-threads, and re-iterations
- whatever you write gets outdated pretty instantaneously - sooner or later, you're out of time (and motivation) to keep it up-to-date
- why bother with writing if the typical attention span these days is so short that people can't be arsed to focus on anything longer than a tweet ...
These all are very popular statements that have one thing in common: they are frequently true. But they don't have to be true at all.
On writing well
How come? Because there's a huge difference between "just writing" and "writing well".
Simply dumping the chaotic entanglement of our thoughts on paper isn't very effective indeed. Quite the opposite. But writing doesn't have to look like that! One has to put into use actual, practical skills - which shouldn't be surprising at all, doesn't it apply to all the abilities?
Well-written text:
- has a clear point (purpose) - a single and meaningful one
- is concise: contains precisely what's needed and nothing else
- is precise: fact-based and devoid of "weasel words" and obviousness
- has a proper form and structure: follows a clear train of thought and uses understandable mental models
- has its message adjusted to an expected audience
When writing is a must
There's a multitude of everyday situations (in software engineering) where good writing is essential, e.g.:
- framing vision, strategy, key principles, or tenets - topics that need to get re-emphasized and re-iterated frequently
- documenting ADRs or other decisions made (for future reference, to provide guidance)
- in a problem solving - to clarify the nature of the issue being addressed and simplify option analysis
- in asynchronous communication: e.g., management summaries, information radiators, etc.
- while documenting the learning outcomes: post mortems, feedback, root cause analysis considerations
- to document "contracts" (between teams, units, products) and success criteria (expectations)
- to cultivate conscious knowledge preservation, e.g., the intent behind the design
YES, so many organizations do NOTHING from that list. That clearly helps them save some time short-term, but ... for what price long-term?
What's in it for me?
Organizational benefits are one thing (a very important one, of course), but what are the pros of writing for an individual? Here we go - writing ...
- ... helps a lot in putting yourself in someone else's (your reader's) boots
- ... is a decent way to validate that you truly understand (and can formulate) your own point
- ... democratizes decision-making processes, so it's easier for an individual to come up and 'sell' a good idea (hereby avoiding negative effects like HiPPO)
- ... is a great tool in sharpening your clarity of thought, brevity and challenging your own ideas
- ... makes it easier to receive (and follow up on) a well-targeted feedback on your thoughts and ideas
From ashes ...
How can I trust someone to deliver a proper solution if (s)he can't express it in an objective, clear and unambiguous form first?
Unfortunately, the writing skill in the vast community of software developers is pretty much extinct. As it is essential, it has to be rebuilt and embedded into our work cultures: by setting up good practices, active coaching, highly visible role models & examples. It's not a fad but a sheer necessity - especially now, in the times of remote work boom caused by the global pandemic.
