My favorite things about working at companies with a culture of writing
founder-fodder.ghost.io
founder-fodder.ghost.io
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.
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)
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.
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.
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.
The expression culture of writing is badly chosen for the tech world
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.
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.
Nice idea, thanks! Is that something you've seen implemented in practice? I'd be curious to see that combined with something like PageRank to determine document importance and credibility.
There were a couple of binders in the office for these & everyone had to sign-off on any new documents on their first duty shift since the doc was posted.
(Part of my job was to check the sign-offs and then tap the shoulder of any laggards to say, "Stop what you are doing and go read the bulletins. Now.")
I'm gonna steal that one.
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.
Surely in a company setting, it is possible to seek clarification from the original writer and then jointly rewrite the confusing parts.
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.
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.
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.
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.
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.
I haven't seen any evidence of a company culture scaling beyond ~10 people - in a bigger group, sub-cultures and individual personalities seem to inevitably take precedence. Arguably this is even more the case at a place like Amazon where raw metrics are king - nobody cares how culturally aligned your work is as long as you are delivering the goods.
I don’t even know if prose would be superior, but I find diagrams to be, almost always, completely meaningless, or at least far more economical to describe with written words, than to create and then present with the ephemeral spoken word.
But go ahead and try writing a long thoughtful prosaic treatise on technical strategy to solve some difficult problem. It will almost certainly be ignored by the people you are trying to influence, and if you’ve been responsible at all with including criticisms of alternative views, it will infuriate people and create permanent enemies. PowerPoint is safe by nature of it’s ambiguity. People look at it, and automatically assume that you are representing their own thoughts. This is how you build agreement on disagreement by abstraction to the pseudo-technical neutral. The project will fail, but you will get promoted. Writing is precise, and contrapuntal, and dangerous to your career.
Edit: Upon reflection, I believe that this has a lot to do with the nature of authority in the business. The company I work for (not specifically my immediate group) currently has a very strong culture of top-down decision-making; very little influence is accepted upward, as well as very little explanation required downward. As a result, everything is ephemeral, and decisions from above change often, so nobody has the ability to break that chain by committing anything to writing.
I also suggest to younger people, try to write your own notes in full sentences instead of just bullet points. This is a good first step towards appreciating writing more, and in my experience helps you organize and remember your thoughts better.
It IS unnecessary. Having to write a wall of text to explain what your code is doing is one of the simplest code smells.
A little bit of very short comments is ok, but in general any verbose comment should always be for explaining the why, listing out some invariant, etc.
As a side note, another reason not to write comments about what the code is doing is because those comments then need to be updated too - and often they would not be leading to more confusion.
Sometimes you can handle this by writing out a test case and document the test case instead. Other times, you can't. It's context-specific.
I don’t ever want to read a comment like “Adds 1 to x, storing the result in y” but most wall of text comments are describing things that you can’t get from just reading the code.
Maybe. Writing bullet points was a good first step towards appreciating writing more for me. Writing well thought full sentences always makes me more anxious, and writing bullet points help me to actually write things down(even allowing me to refactor to full sentences when necessary, like when writing an email, slack messages or blog posts).
I find they often end up changing or removing it.
I have a feeling that writing explanatory code comments (as in _why_ something exists) about non-conventional code might come naturally when you've really thought something through. Where vice-versa undocumented non-conventional code might be a sign that they just got something working without really thinking about how it _should_ work.
Like another pointed out, what about a culture of reading? And further, what are these cultures of writing doing to help individuals improve their writing? Understanding audience, valuing brevity, tone, structure, knowing when not to write, etc are all important skills that the vast majority of people in business (probably including me) lack.
Further, writing takes time. How do you evaluate what writing is worth it, that the time you take away from e.g. coding still adds business value? It certainly may, but that feels very hard to quantify.
I write in a manner similar to how I design software. I use an "evolutionary design" approach[0]. My writing tends to be a rather loosely-organized, casual, vernacular.
[0] https://littlegreenviper.com/miscellany/evolutionary-design-...
Hm, I do wonder what James Damore would have to say about that
At which point anything you have written, past or present, can, and will be used against you.
Heck, getting fired is nothing. People have had their PhDs cancelled...
At my last workplace, I was chewed out for doing so because apparently I was "wasting time".
But we ended up wasting a lot more time over subsequent months because nothing was concrete, so plans kept changing, people constantly misunderstood, stuff had to be re-explained and discussed with people who'd forgotten or hadn't paid attention or who'd joined the team late, it was a mess and it really kinda pissed me off.
My current workplace is better in this regard, where stuff can be planned and finalised and put to paper before we begin working on the implementation.
Here's more of a general cultural topic: When people say "I was chewed out at work", then what does that entail?
I'm Swedish, I'd call "being chewed out" to be asked questions on how I'm doing some part of my job, for example planning. Is this what people mean?
I'm exaggerating a bit, but in Swedish workplaces you can have a relatively light touch and still have great effect imho.
No, I would hate to treat anyone else that way.
For reasons that I don't want to get into right now, it's not easy for me to find work that pays well. But I did start looking once I realized how toxic the workplace was, and moved to the next when I could.
>For reasons that I don't want to get into right now, it's not easy for me to find work that pays well.
Just to be clear: I wasn't expecting you to defend your behavior in this particular case, that would be cruel and unsympathetic of me to say the least. I was only interested in how in general this treatment can occur in places where people are well paid and highly educated (with the implication that they're likely to find work regardless).
"Writing is nature's way of telling us how lousy our thinking is." [1]
[0] https://en.wikipedia.org/wiki/Leslie_Lamport
[1] https://www.goodreads.com/author/quotes/523508.Leslie_Lampor...
My only advice, and I am by no means perfect... Is to use bullet points!
Plus, it's not like you can't include the occasional illustration or even animation, both of which can really get the point across well at times!
You still should have these docs and pieces of text since there is a lot of value in them, just don't overcomplicate them.