I work at a company you’ve all heard of that prides itself as a place where everyone writes and everyone reads. A lot.
I’m an individual contributor. In theory, my job is to build stuff, which - again, in theory - involves writing code, debugging, solving deep technical problems, and so on. Unfortunately, due to the culture of writing and reading I spend most of my time mired in documents. Every breath we take produces a wall of text that must be reviewed and commented on. At this point it’s been about three weeks since I’ve written code.
Not every question deserves the dreaded one-pager. Not every potential code change must be foreshadowed by an exhaustive treatment in a peer reviewed design doc. Not every potential failure mode must be imagined and written up in detail, including all hypothetical gory details.
And don’t you dare protest! You’ll be labeled not a team player, poor communicator, a lone wolf. You’ll get a negative performance rating in the next cycle and then “managed out” for non-compliance with prevailing culture.
Oh, performance reviews are a special kind of joy. For a few weeks each year the economy of writing traffics mostly in documents written by employees who must openly brag about work they did over the past year. It’s a kind of literary hunger games in a corporate setting.
Oh, and this Kafkaesque machine has feelings too. It’s weird about “tone”: disagree with someone’s writing and they see a personal attack. Sickly sweet praise is the name of the game, whereas legitimate critique of another’s writing must be circumspect and formed such that it cannot be “taken the wrong way” or else!
This is classic "optimization of x destroys the rest of the alphabet." I wish more businesses employed some sort of systems thinking and realized that rules are coordination mechanisms that carry the capacity to destroy value. They're absolutely great when they create predictability and coordination at minimal cost, but they can destroy your company if all they do is impede activities that generate the value your business actually earns profit from.
In my experience, most businesses with these kind of over-documentation practices are conscious of the value loss. The executives just believe, rightly or wrongly, that the issues being averted would themselves destroy the company if they happened.
This is one of the most concise formulations of the topic I stumbled across in my time on this planet. Thanks. Already added it to my notes regarding systems, processes, system thinking and rules.
I also work for a company where everyone writes and reads and we have almost no meetings at all, no scrum, etc, and I didn't notice any of these problems. It's the best place I've worked at and I'm already > 20 years into this.
To me the problem you describe is orthogonal to the fact you have a writing culture or not. I bet if you didn't have that writing culture you would still have all those problems and just a ton more meetings and conversations with managers. I've been at places like that in the past and the best solution for me was to quit, I just couldn't stand it.
For example, promotions: I've been in that hunger games you mention where you have to promote yourself to death to have a promotion, and I hated it. Agree with you it was a real problem, specially for people that don't like to do marketing of themselves. At my current company your team lead is ultimately responsible of the output of the team, so with consideration of the team's opinions, he ultimately decides if you get a raise each year or not. If he wants you in the team you get a raise, if he doesn't you get a lower one or none at all. You can look for another team within the company or you can leave, up to you. Leads are professional enough like to not promote just friends, because they're also accountable in the same way up the chain. And that's it. At the end of the day your team, the 6 or 10 people you work with every day, they know very clearly if they want you or not, no need for 100 page essays about your awesomeness.
You're not being very Googley. Report for reeducation. Non compliance will result in 2x the number of peer reviews during the next perf cycle and failure to complete them on time will get you a PIP. Shortly thereafter, you will be exited. You have been warned.
> Not every question deserves the dreaded one-pager.
Since I have no context on your company or their process, can't say anything specific.
You're totally right that not every thing requires the full process. Processes must be flexible to accomodate the simple cases as well as the complex ones.
That said.. most of my experience is that developers do like to complain about following documentation process even for many cases where it is very much necessary.
When I'm working with someone new I pay attention to their writing for a while to see how much effort/attention to detail they put into it, and then basically match. It's the best heuristic I know for not wasting effort on writing since typically someone rushing through writing will do the same with reading.
Always a pleasant experience meeting new co-workers who care about writing though.
Greatly agreed this is a better way to think about it.
Self service documentation is definitely one way. Writing great documentation to help others come up to speed. But you also need a culture of actually looking for answers in documentation yourself. Also realize that some people don't learn that way. I made trainings in video and wiki form for a group a started, I did the same documentation in a video. For 70% of the people in my group the video clicked better. They use the wiki more as a rubric. So having both works well, however the video was quite time intensive to make.
Another way is what people talk about for Amazon, which you may be referring to. While plenty of communication happens verbally or in hallways, the important communication happens in writing and then discussion of that writing. And you are correct it is all about a culture of reading to understand that idea. And then writing again to update it.
It is more a culture of searching then. Joking aside. Culture of writing usually includes the fact that people search by themselves for information and that information is stored in a central place. Otherwise we would call the Slack threads culture a culture of writing too.
The expression culture of writing is badly chosen for the tech world
Counterpoint: Confluence, by itself a great tool, just by hearing its name is making my eyes hurt from all the rolling.
I can't count the projects I took part in, in which the "knowledge database" had grown in to a gigantic, helplessly out-dated pile of words. Few people read another persons content, thus even less correct/update it. Finding anything usually involves scrolling through redundant search results and entries.
I know clean-code can't solve everything but I find self-explanatory code to be a major time-saver: less need to write documentation, less need to update documentation, easier getting an understanding of the code.
For everything more meta, there are still comments or e.g. infrastructure files. And ultimately the README.md. Looking into a package.json or docker-compose.yml often was more helpful if not a requirement to make sense of Confluence's content at all.
(I also empathise heavily with the morass-of-distributed-documentation problem. a bit like coding, I think that although every code change should be documented (with reasoning, explanation, etc), organizations should try really, really hard to reduce the amount of written documentation required for products and services in the first place. a bit like the best code being the code that doesn't exist, it's much easier for folks to read and consume information when it's concise, well-organized and clear)
Collecting the signatures of readers at the bottom of important documents is pretty effective ;)
In my experience (as someone who enjoys both reading and writing) it's generally a question of demonstrating the concrete value of reading and producing written artifacts. I tend to start with teaching people how to write because it provides the most tangible outcomes: an outline, a plan, a draft, or a memo. When you're able to coach someone into expressing a raw idea of theirs as words on a page, the value of writing becomes clear very quickly.
From there, it's a matter of them warming up to the notion that internalizing the writing of others works in the opposite direction. Once they understand that reading and writing is the process of serializing and deserializing mental models (and that the result of this process is lossy at best, and actively misleading at worst), that's when the switch flips from "casual" to "critical" reader, and "amateur" to "practiced" writer, in my opinion.
I agree with most, if not all, the points raised in the post. I'm curious how people deal with:
1. Organizing knowledge. Too often I've seen a lot of well-written and well-intended information thrown into a shared cloud drive or wiki to rot and grow stale. You end up with multiple, sometimes contradicting documents about the same topic, finding what you're looking for is difficult, and before you know it people revert to tribal knowledge and slack DMs to find out what they need.
2. A writing culture can penalize and demoralize non-native speakers whose writing skills may not be as strong as their peers. I've worked with brilliant individuals who felt like they're perceived as "stupid" because their language skills weren't as polished.
If you have a writing culture, you have management support to not mark work as done until documentation is updated. If someone asks for support because the documentation didn't answer their question, the support ticket is not closed until the documentation's language is improved and clarified. This is usually a good trade-off for management: the time spent keeping documentation up-to-date is repaid many times over by people who are able to help themselves instead of having seniors be continually interrupted. Note that this return is not necessarily realized for very small companies or companies where employee churn is low - this is generally true for large companies and growth-stage companies.
> 2
Companies have a choice, they can: a) decide not to hire people who won't be a cultural fit, b) invest in training to try and align people to the preferred writing culture, c) invest in dedicated roles like technical writers who can sit alongside engineers with poor writing skills, at the gain of being able to hire engineers with poor writing skills, at the cost of additional overhead due to the additional technical writer hire.
> The problem there isn't that the company has a writing culture.
English is my second language... not that anyone would notice. I've spent enough time writing fiction that I'm better at it than most people for whom it is native. Recently I've noticed I've started making the same homophone errors that actually native speakers tend to make; not sure if that is good or not.
But that's a huge time investment. If such companies want to pay people to spend three or four hours a day, for years, training their writing skill -- then sure, I don't think anyone will mind. Otherwise I don't think it's a reasonable request.
For #2, I think any company employing people where the going language is not their native language should invest in language courses.
I live and work in NL but a lot of companies have international employees, which means the going language is English. But it's English where nobody speaks it natively, so you end up with this kind of expat-English.
Companies like that should invest in either weekly class-based lessons, or mandatory one-to-one language classes through e.g. online. Spelling, grammar, writing and speaking practice, as well as culture classes.
And related to the article, typing classes. I've encountered multiple people now working in IT, whose job is reading and writing (code, documentation, emails, whatever) who cannot touch type. I don't think not being able to express oneself on a keyboard in a quick way is acceptable anymore. I can recommend typing.com, five minutes a day at least, it doesn't take that long to learn touch typing.
Regardless of skill, you're always going to have to be tolerant of others and their limitations. You probably have a couple of good people in your company with dyslexic tendencies, for example.
Is touch typing really a big deal for most people who aren't copying documents? I'm a pretty fast typist but not a touch typist. It just never seemed like a big enough deal to learn. My typing speed certainly doesn't seem to get in the way of anything.
re #2: Being a non-native speaker is fundamentally going to make things more difficult, but when the alternative is meetings with different accents and no time to look unfamiliar words up, a document culture seems far more accessible.
That's a good point. The wider issue is of course that some people are smart, but not good at writing, and they might be sidelined in an organisation that leans heavily on writing. However, the corollary of that is smart people who are not good at talking get sidelined in an organisation that does a lot of talking. So that's an issue you will always have: the form of communication you focus on will always put some people at a disadvantage. It just means you have to be aware of that, and try and keep an eye open for people who have important things to say, but are struggling to get them across.
I find listening to heavy accents and persons struggling to find the correct words far more taxing than reading materials with confusing grammar and choice of words.
Surely in a company setting, it is possible to seek clarification from the original writer and then jointly rewrite the confusing parts.
It is also a good idea to partner such persons with a good native writer, even if they are not as advanced technically. Then both persons improve in their respective areas.
1. Dedicated curation. Part of what makes the NodeJS project so successful is the formal curation applied to its documentation.
2. Writing takes practice. Ignoring this due to any bias is a case for institutionalizing ignorance. At my current employer I see much better writing coming out of India from non-native speakers/writers.
One of the best things that came out of Amazon was the popularization of writing memos to ensure the meeting organizer and attendees had thought out the problems they are trying to solve upfront and use the meeting time to read and make a decision. Arguably how meetings should be conducted if you're into the Peter Drucker/Andy Grove philosophy.
Just about everything in this article are principles I value in any company. When you have a "write it down" culture, you get all these benefits and then some. What I have noticed in big tech however is the anti-pattern that most people in lower leadership positions are often mediocre writers and politician players. The best writers? Usually individual contributors or leading entire organizations.
For developers who don't like to write, but like to express their ideas, I've found a "RFC" (request for comments) process to really clarify the thinking, get the right feedback, and ultimately make teams make higher quality decisions together before writing any code.
Anyway you put it, a culture of writing is crucial for success.
For me, the single biggest advantage of a writing-oriented culture is that it's more remote-friendly. Even the "road shows" OP mentions don't get to people who work in "odd" locations. I was fully remote for years even before COVID, but I was always close to an office. That meant I could go in when there guests showed up (assuming I heard about it in time). However, I could just as easily have worked too far away for that, and there's a lot I would have missed out on.
Also, this suggests a type of interview that I've never seen IRL: make someone write text, not code. Give them a topic and a laptop, let them Google as much as they want, and leave them alone for fifteen minutes. For a whole bunch of reasons, I think that's much more realistic than making people write code on a whiteboard in front of people, and candidates who do well at it are much more likely to do well for real.
Then again, maybe this is all motivated reasoning because I would have benefited personally from a greater focus on writing (and reading) at companies where I worked. At my last company I feel I was actively screwed because writing wasn't valued at all.
I’ve always felt that quality of writing is one of the best signs of a good candidate for hire, well before tech skills, and is something I factor heavily while hiring. But now that you mention it, our candidate projects generally are just code focused plus discussion, which is unfortunate, and probably worth revisiting.
Having worked at a writing-based company, any time I have to sit through a PowerPoint is now painful: Do I ask a question about the topic I care about now? Will we get to that topic later, and the speaker is just providing needed background context? Or is the thing I really care about sandwiched in at the end? Should I tell the speaker that we already know about all the stuff he's talking about now? On this next slide, should I tell the speaker that all the thing he just said are "basics," I've never heard of?
Having a document to read gives the time to read faster through things that don't require as much attention, and read slower through things that require more attention, and maybe even stop and google things that you don't know so you have needed background.
I’m in a company where English is not our native language, yet we write almost everything in it. Being a second language I sometimes need to phrase and rephrase my ideas while writing them. I found that it sharpens my thinking.
As a native English speaker, I also phrase and rephrase my ideas while writing things in English.
In my experience, the exercise of fine tuning what you are and aren’t saying is one of the main reasons to write it in the first place, because it’s actually helping you figure out what you are and aren’t thinking too.
As a native english speaker, oftentimes I find myself rearranging my own sentances and paragraphs and discovering the exact same thing. Reducing overly verbose text similarly generatesx the same focus to thoughts.
Readit News
I’m an individual contributor. In theory, my job is to build stuff, which - again, in theory - involves writing code, debugging, solving deep technical problems, and so on. Unfortunately, due to the culture of writing and reading I spend most of my time mired in documents. Every breath we take produces a wall of text that must be reviewed and commented on. At this point it’s been about three weeks since I’ve written code.
Not every question deserves the dreaded one-pager. Not every potential code change must be foreshadowed by an exhaustive treatment in a peer reviewed design doc. Not every potential failure mode must be imagined and written up in detail, including all hypothetical gory details.
And don’t you dare protest! You’ll be labeled not a team player, poor communicator, a lone wolf. You’ll get a negative performance rating in the next cycle and then “managed out” for non-compliance with prevailing culture.
Oh, performance reviews are a special kind of joy. For a few weeks each year the economy of writing traffics mostly in documents written by employees who must openly brag about work they did over the past year. It’s a kind of literary hunger games in a corporate setting.
Oh, and this Kafkaesque machine has feelings too. It’s weird about “tone”: disagree with someone’s writing and they see a personal attack. Sickly sweet praise is the name of the game, whereas legitimate critique of another’s writing must be circumspect and formed such that it cannot be “taken the wrong way” or else!
I’m so done.
To me the problem you describe is orthogonal to the fact you have a writing culture or not. I bet if you didn't have that writing culture you would still have all those problems and just a ton more meetings and conversations with managers. I've been at places like that in the past and the best solution for me was to quit, I just couldn't stand it.
For example, promotions: I've been in that hunger games you mention where you have to promote yourself to death to have a promotion, and I hated it. Agree with you it was a real problem, specially for people that don't like to do marketing of themselves. At my current company your team lead is ultimately responsible of the output of the team, so with consideration of the team's opinions, he ultimately decides if you get a raise each year or not. If he wants you in the team you get a raise, if he doesn't you get a lower one or none at all. You can look for another team within the company or you can leave, up to you. Leads are professional enough like to not promote just friends, because they're also accountable in the same way up the chain. And that's it. At the end of the day your team, the 6 or 10 people you work with every day, they know very clearly if they want you or not, no need for 100 page essays about your awesomeness.
Since I have no context on your company or their process, can't say anything specific.
You're totally right that not every thing requires the full process. Processes must be flexible to accomodate the simple cases as well as the complex ones.
That said.. most of my experience is that developers do like to complain about following documentation process even for many cases where it is very much necessary.
We obviously write a ton of docs but only when we need to. Personally I code 60% of the time as an IC L5 (software engineer)
I spent a lot of time on an exhaustive readme, but at best people skim it and ask questions or make the same mistakes I made again.
Writing is cool and all, but make sure you have a system in place, an index, and a culture of telling people where to find what.
Always a pleasant experience meeting new co-workers who care about writing though.
Self service documentation is definitely one way. Writing great documentation to help others come up to speed. But you also need a culture of actually looking for answers in documentation yourself. Also realize that some people don't learn that way. I made trainings in video and wiki form for a group a started, I did the same documentation in a video. For 70% of the people in my group the video clicked better. They use the wiki more as a rubric. So having both works well, however the video was quite time intensive to make.
Another way is what people talk about for Amazon, which you may be referring to. While plenty of communication happens verbally or in hallways, the important communication happens in writing and then discussion of that writing. And you are correct it is all about a culture of reading to understand that idea. And then writing again to update it.
The expression culture of writing is badly chosen for the tech world
I can't count the projects I took part in, in which the "knowledge database" had grown in to a gigantic, helplessly out-dated pile of words. Few people read another persons content, thus even less correct/update it. Finding anything usually involves scrolling through redundant search results and entries.
I know clean-code can't solve everything but I find self-explanatory code to be a major time-saver: less need to write documentation, less need to update documentation, easier getting an understanding of the code.
For everything more meta, there are still comments or e.g. infrastructure files. And ultimately the README.md. Looking into a package.json or docker-compose.yml often was more helpful if not a requirement to make sense of Confluence's content at all.
(I also empathise heavily with the morass-of-distributed-documentation problem. a bit like coding, I think that although every code change should be documented (with reasoning, explanation, etc), organizations should try really, really hard to reduce the amount of written documentation required for products and services in the first place. a bit like the best code being the code that doesn't exist, it's much easier for folks to read and consume information when it's concise, well-organized and clear)
In my experience (as someone who enjoys both reading and writing) it's generally a question of demonstrating the concrete value of reading and producing written artifacts. I tend to start with teaching people how to write because it provides the most tangible outcomes: an outline, a plan, a draft, or a memo. When you're able to coach someone into expressing a raw idea of theirs as words on a page, the value of writing becomes clear very quickly.
From there, it's a matter of them warming up to the notion that internalizing the writing of others works in the opposite direction. Once they understand that reading and writing is the process of serializing and deserializing mental models (and that the result of this process is lossy at best, and actively misleading at worst), that's when the switch flips from "casual" to "critical" reader, and "amateur" to "practiced" writer, in my opinion.
1. Organizing knowledge. Too often I've seen a lot of well-written and well-intended information thrown into a shared cloud drive or wiki to rot and grow stale. You end up with multiple, sometimes contradicting documents about the same topic, finding what you're looking for is difficult, and before you know it people revert to tribal knowledge and slack DMs to find out what they need.
2. A writing culture can penalize and demoralize non-native speakers whose writing skills may not be as strong as their peers. I've worked with brilliant individuals who felt like they're perceived as "stupid" because their language skills weren't as polished.
If you have a writing culture, you have management support to not mark work as done until documentation is updated. If someone asks for support because the documentation didn't answer their question, the support ticket is not closed until the documentation's language is improved and clarified. This is usually a good trade-off for management: the time spent keeping documentation up-to-date is repaid many times over by people who are able to help themselves instead of having seniors be continually interrupted. Note that this return is not necessarily realized for very small companies or companies where employee churn is low - this is generally true for large companies and growth-stage companies.
> 2
Companies have a choice, they can: a) decide not to hire people who won't be a cultural fit, b) invest in training to try and align people to the preferred writing culture, c) invest in dedicated roles like technical writers who can sit alongside engineers with poor writing skills, at the gain of being able to hire engineers with poor writing skills, at the cost of additional overhead due to the additional technical writer hire.
Couldn't you say this about basically any skill?
> I've worked with brilliant individuals who felt like they're perceived as "stupid" because their language skills weren't as polished
The problem there isn't that the company has a writing culture.
English is my second language... not that anyone would notice. I've spent enough time writing fiction that I'm better at it than most people for whom it is native. Recently I've noticed I've started making the same homophone errors that actually native speakers tend to make; not sure if that is good or not.
But that's a huge time investment. If such companies want to pay people to spend three or four hours a day, for years, training their writing skill -- then sure, I don't think anyone will mind. Otherwise I don't think it's a reasonable request.
I live and work in NL but a lot of companies have international employees, which means the going language is English. But it's English where nobody speaks it natively, so you end up with this kind of expat-English.
Companies like that should invest in either weekly class-based lessons, or mandatory one-to-one language classes through e.g. online. Spelling, grammar, writing and speaking practice, as well as culture classes.
And related to the article, typing classes. I've encountered multiple people now working in IT, whose job is reading and writing (code, documentation, emails, whatever) who cannot touch type. I don't think not being able to express oneself on a keyboard in a quick way is acceptable anymore. I can recommend typing.com, five minutes a day at least, it doesn't take that long to learn touch typing.
So this is a big thing in EU politics: https://en.wikipedia.org/wiki/Euro_English
Regardless of skill, you're always going to have to be tolerant of others and their limitations. You probably have a couple of good people in your company with dyslexic tendencies, for example.
Surely in a company setting, it is possible to seek clarification from the original writer and then jointly rewrite the confusing parts.
2. Writing takes practice. Ignoring this due to any bias is a case for institutionalizing ignorance. At my current employer I see much better writing coming out of India from non-native speakers/writers.
Just about everything in this article are principles I value in any company. When you have a "write it down" culture, you get all these benefits and then some. What I have noticed in big tech however is the anti-pattern that most people in lower leadership positions are often mediocre writers and politician players. The best writers? Usually individual contributors or leading entire organizations.
For developers who don't like to write, but like to express their ideas, I've found a "RFC" (request for comments) process to really clarify the thinking, get the right feedback, and ultimately make teams make higher quality decisions together before writing any code.
Anyway you put it, a culture of writing is crucial for success.
Also, this suggests a type of interview that I've never seen IRL: make someone write text, not code. Give them a topic and a laptop, let them Google as much as they want, and leave them alone for fifteen minutes. For a whole bunch of reasons, I think that's much more realistic than making people write code on a whiteboard in front of people, and candidates who do well at it are much more likely to do well for real.
Then again, maybe this is all motivated reasoning because I would have benefited personally from a greater focus on writing (and reading) at companies where I worked. At my last company I feel I was actively screwed because writing wasn't valued at all.
Having a document to read gives the time to read faster through things that don't require as much attention, and read slower through things that require more attention, and maybe even stop and google things that you don't know so you have needed background.
In my experience, the exercise of fine tuning what you are and aren’t saying is one of the main reasons to write it in the first place, because it’s actually helping you figure out what you are and aren’t thinking too.