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.
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.
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.
> 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.
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.
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.
I like this culture too, and I wish it was more prevalent. Unfortunately, many developers today oppose it, writing explanatory code comments in natural language is seen as unnecessary, and documentation in natural language is seen as an afterthought.
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.
> writing explanatory code comments in natural language is seen as unnecessary
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.
Good documentation explains that which is not naively understandable. Most production-hardened code has lots and lots of code that deals with edge cases. A new employee might look at all the code that deals with the edge cases, think "this is needlessly complicated", and rip it out.
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.
“This algorithm was chosen to ensure compliance with regulation XYZ.” “This planner takes into account inbound logistics delays and temporary out of stock conditions.”
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.
>try to write your own notes in full sentences instead of just bullet points. This is a good first step towards appreciating writing more
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).
When I find code I don't understand the purpose of in code reviews I ask the author to document the purpose in the code so that the next person (likely future them) won't be confused by it like I was.
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.
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.
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
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.
I'm the kind of person who likes to write stuff out while planning or figuring something out.
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.
And why do highly educated people with well paid jobs accept this treatment? Is it because they want to treat others the same too? Before you ask: Yes, I am naive and ignorant :-).
Lots of people are shy or quiet or introverted and thus unwilling or unable to push back against this kind of thing (or see through it when it's bluster).
You're assuming that (i) I'm highly educated, (ii) I was well paid, (iii) I accepted the treatment and (iv) not accepting the treatment was an option.
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.
Yeah, I know that I made some heavy handed assumptions based on where we are (HN). Especially considering that 1 and 2 would make 4 more likely to be true, and 1 and 2 is likely true on HN AFAICT.
>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).
It's a very colloquial term that covers a lot of ground. Yes, it could mean that they were yelled at in a room full of people. It could also mean they were informally and quietly requested to do something a different way next time.
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, 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.
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.
Amazon often pitches itself as having a "writing culture", but much like the LPs and other mantras like "working backwards", this is more a case of cult-like exceptionalism than any sort of actual advantage once viewed from the inside.
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.
Scientific progress has been enabled by well written materials. Most seminar presentations are an overview of the material which inspires interested persons to read the actual papers for more details.
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.
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.
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.
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.
> Collecting the signatures of readers at the bottom of important documents is pretty effective
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.
Back in the pre-internet era this is how bulletins and vital memos were handled in the airlines.
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 have seen it in practice, and I've done it in the past: the thing to keep in mind with this approach is that it's generally most effective when the contents of the document will have a critical impact on the reader's work, and when each signatory contributed something to its creation. In the wrong context, asking for a signature can come off as distasteful or overly bureaucratic, so it's best to avoid leaning on this as a common practice.
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.
Is this really an argument, though? Certainly for any communication style X, some people will struggle with X. Even then, if, for example, speaking demonstrably had far fewer "strugglers", does that automatically make it preferable?
I’m all for culture of writing, but that feels too easy.
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've been writing for most of my life. I'm fairly good at it; but nowhere near a professional writer.
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.
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 am exhausted by the use of powerpoint as a replacement for well-formed prose.
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.
My SO is a designer for a very large well known tech multinational. It amuses me when she has to design charts and presentations, and comes asking questions with a childlike naivite towards pretty deep technical stuff. Also makes me think of the other designers without the benefit of sharing the house with someone with a bit of knowledge and how their work probably ends up more confusing than anything.
Writing is very important. My partner has worked at two of the FAANGs and often times could not understand what anyone was even trying to say. Surprisingly the smartest people in the world are also amongst the worst writers in the world.
My only advice, and I am by no means perfect... Is to use bullet points!
Bullet points have their place, and I certainly use plenty of them myself, but I'm not sure it's the first piece of advice I'd give. I think my #1 point would be that good technical "writing" is not just writing. The best technical docs I can think of also included good diagrams and tables (not meme pictures), visually distinct example code or commands, footnotes and sidebars to keep the main text uncluttered, etc. You don't have to be a full-out graphical designer, but a little work on making something besides an impenetrable wall of text can go a long way toward making a document more readable.
81 comments
[ 4.0 ms ] story [ 172 ms ] thread1. 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.
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.
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.
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).
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.
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...
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 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.
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.
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.
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-...
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 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.
"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!