Encouraging a culture of written communication
mcls.io
mcls.io
I think one thing that's needed to establish a culture of written communication is getting rid of any cultural elements that allow people to use the avoidance of reading and writing as an expression of power. You can frequently determine the balance of power between any two people in an organization by seeing which one has to read and prepare organized documents and presentations, and which one can simply speak and be spoken to. People want to paint pictures of themselves as being able to synthesize knowledge and ideas instantly, utter commands in real time and see them turned into action. In the other direction, they have no time for reading - you must request an audience with them and survive their real-time verbal sparring and probing questions to have your ideas received and considered.
My other musing on this is that I've always wondered if there would be value in teams establishing an internship or low/mid level position for a technical writer to serve as a team librarian. "Easy to search" is good, but "search" itself is not sufficient for many situations - what you need is a person who can answer questions while taking context into account. If I was running a technical team, I'd love to experiment with hiring someone whose primary accountability is answering everyone else's questions, not generating output. In the same way that a good dev needs to organize their workspace and build tools/scripts to be successful, this person will end up organizing the team's information to better accomplish their job.
What if I'm just bad with the async nature of slack and/or email? If I had a nickel for everytime a long drawn out back and forth email thread that was resolved in less than two minutes with a face to face conversion and a white board I would have a shit load of nickels.
I’ve had a lot of 1on1s meant to “get us all on the same page” where a boss just blithers and blathers for an hour without communicating anything. The value in writing is working through the mistakes your brain makes during communication. Going to talking just makes it easier to ignore errors.
It's possible to "resolve" something / determine what to do next without writing anything down.
Often the ideal outcome is simply an agreement that Person X will move forward with approach Y.
Which you can write down if you so desire.
Slack and other instant messaging tools may make it feel like you need to be always on and responsive, but instant messaging is at odds with async.
> what you need is a person who can answer questions while taking context into account.
A secretary. Teams need a secretary. Also to help wrangle the explosion of communication tools developers have to use these days.
I think a lot of inefficiency and wasted developer-brain-bandwidth on development teams could be solved with secretaries. But I've never seen it done. Probably part of the "with computers everyone can DIY their secretarial work, so now they must" and the shift (even farther) into secretaries being a status symbol more than anything else, and god knows we mustn't let developers have status (pay yes, status... oh hell no).
When I think of my own company, such a person would ideally be tasked with reading the user guides of the tools we use and quickly answering questions of the form "can we do this with it?", amongst other things.
This article is good but like others it focuses on the problem of getting people to write. I've found it's much harder to get people to read. The dirty secret of most workplaces is the massive disparities in reading speed that exist and the subtle tensions that can cause. It's something myself and my manager have both wrestled with, as we both read much faster than some of the other less technical people in the firm, and thus don't think much of dropping a six page memo on people or having long/complex discussions on Slack. Then they get frustrated at the implied expectation (sometimes that they put on themselves) to read it all.
Not at all! They'd often have to train in procedures and lingo for various occupations, so they wouldn't screw it up and could be maximally useful. Medical secretaries, for example, were once a pretty big occupation (I'm sure they still exist, but there were once lots of them) and they absolutely had to train in e.g. medicine names and greek and latin prefixes and meanings (beyond just mega- or whatever). Secretarial training, often with a focus on an in-demand field, used to be something community and junior colleges offered. "Some level of technical knowledge" is consistent with the role secretaries used to perform and the skills they used to have, in many cases, at least when "secretary" didn't mean "door and phone answerer". Acting as an advanced, human file search and process figurer-outer ("can we do this with it?") was also part of their role, coming with the territory of being responsible for filing (and often for producing the documents being filed in the first place).
If we have to go with "team librarian" for language/marketing reasons I'm still on-board, but "secretary" would be a fine label. That their often possessing significant domain knowledge not just as a side-effect of employment & experience but as part of their training is (perhaps?) no longer common knowledge is a sign of how far out of favor real professional-secretarial (that is, secretary to professionals) roles have fallen, I guess.
That's even before we get into second order effects of building new pathways into technology work.
It's an interesting idea, but I think the problem is that someone who can do this role (the intersection of technical competence and desire) is going to be exceedingly difficult to find or may not exist at all.
Someone that's going to be capable of providing useful answers to developer questions is likely to be a developer themselves, and almost certainly they're not going to stick around in that position for long. Part of being an effective "librarian" in this way is going to be knowing where to go to get a specific answer -- the existence of specific documentation, which group/team/person is responsible for which component, the levels of expertise of people on teams so you can immediately contact the lowest level person capable of answering, and eventually just knowing answers yourself. All of that comes with time, and if you have high turnover this isn't going to happen.
Also, someone that does the role poorly is going to be worse than nothing: unnecessarily bothering others for (maybe the wrong) information, providing incorrect answers, and/or making incomprehensible documentation. My guess is it's probably hard to judge someone's performance at this until they've been doing it for at least a couple weeks. If you also have high turnover, you will end up with people not suited for this role.
If anyone reading this is in a position to hire for a "technical writer/librarian/secretary/developer assistant," click my username and send me an email. We can try a short-term contract and see how it goes.
I've definitely applied to positions similar to what you've described, but as cold applications, they went nowhere. If I decide to return to regular W2 employment, I'll be sure to keep an eye out.
I pair people with questions with people with answers. I synthesise business requirements into usable tickets. I take ownership of cross-team tasks to make sure they don't get stuck. I digest a lot of information, and share the relevant bits with the relevant people. I make sure that important conversations happen, and that important things aren't forgotten.
In other words, I take care of all the details that would prevent the team from being focused and productive.
It's pretty fun. I am told to make things smoother, but left to decide how to do it.
This is perverse and contemptible in the 21st century. It reminds me of the line from the Simpsons movie: “I was elected to lead, not to read”. But it goes to show that any cultural change needs to come from the top in order to be effective.
> I think one thing that's needed to establish a culture of written communication is getting rid of any cultural elements that allow people to use the avoidance of reading and writing as an expression of power.
I'm not in love of the idea of assigning a team librarian or scribe. I really want it to be part of the culture. Up to the executives. But if someone could demonstrate it works (and how it works), I could be persuaded.
One rule I try to impress on my team: you should be answering common questions whenever you can with a URL rather than a wall of text. That URL can link to a wall of text (or hopefully something a little better structured). Ideally in our wiki. That beats eight different people answering the question eight different ways. Or the same person answering it eight times in slightly different ways.
Very few people are going to be great at solving problems, great at expressing that in new code, great at maintaining existing code, great at debugging, great at testing, great at deployment, and great at documentation.
Specialization makes a lot of sense in many contexts, and writing documentation is one of them.
If I remember rightly, this is actually one of the core ideas in The Mythical Man Month.
Writing requires you to put your name on your ideas. It promotes other pro-social traits, like being vulnerable. It's a lot harder to do negative politics if you're required to take your claims to paper. It's a lot harder to spread misinformation if you have other folks in the organization that can easily go look up your claims and fact check them.
Taking everything "offline" is a great way to bully, lie, cheat, and steal without fear of accountability. It hides incompetence. Weak leaders avoid writing lest they be exposed.
It was infuriating. I'd send him an email, spelling out a need or a project, and he'd walk three stories of stairs to come into my office to make his commitments.
For me, I believe in being held accountable.
You may have noticed that I take a rather unusual tack with my HN ID. I have full access and traceability in it. I have my personal brand attached to it.
That encourages me to be very careful about what I post.
I would love it if we were all more careful about what we post and say.
I have no control over others, so I make sure that I abide by my own standards.
Either they reply or don't. Either way you have established the paper trail. Possession might be nine tenths of the law, but the other ten tenths are coming to court with written evidence to defeat verbal evidence.
It's an excellent way to leave an audit trail.
Scott Adams once wrote a book: "The Way of the Weasel." It has some techniques in there that are remarkably familiar.
What if the communication tool can help to sort out communication messinnes and produce knowlege base as team uses it. Like this one https://9mcollab.com/
Full disclosure: I am advisor to young team behind it
I disagree that this would be a low/mid level position. In fact, I think it would be one of the highest ranking technical positions on a team, on the level of "library maintainer".
Documentation is useful because it allows the writer to transfer their own mental model to the reader. Like any data transfer, the fidelity of the reader's copy cannot exceed that of the writer's copy. So the writer ought to be the person on the team with the best mental model.
Unfortunately, newer developers tend to generate the most documentation by organic processes (in the form of notes and questions based on conversations with more experienced developers). In contrast, more experienced developers tend to silently figure things out without consulting another person.
Another issue is that developers with the best mental models tend to do a good job of assimilating that information into their global "context". This assimilation can make it difficult for these experienced developers to serialize their mental models into documentation, since the boundary between "mental model" and global "context" disappears.
For example - think about how you'd explain HTTP to a random stranger who has never programmed before. It's difficult to know where to start! Beyond that, it's hard to know what mathematical background to assume, how to topologically-sort topics s.t. you never use a term before it's introduced, how to prevent confusion, and everything else that makes teaching difficult.
In conclusion, I maintain that it really takes someone knowledgeable to write documentation which is: 1. scoped to a coherent audience and purpose 2. accurate across multiple layers of abstraction 3. resistant to documentation rot (without resorting to ambiguity)
Ideally, technical documentation would be written by the most knowledgeable person available.
What posts like this do not address is the root cause of the problem: Writing is hard. Why is it hard? And how can people learn to write better? Those would be worthy topics for a longer post, which are not addressed in this one.
Writing, like code, takes time to produce and consume. Like a product with friction in its onboarding, this decreases the likelihood that many people will ever reach the goal of writing clearly.
Unlike code, most people think they can write. But the difference between writing, and writing clearly, is large.
Unlike code, almost everyone has been "taught" to write, often by teachers who themselves do not write well, or do not have time to truly teach them, so they have a lot of bad habits. These include a reliance on cliches, ambiguous diction, and poor organization. The first flaw makes the reader zone out, the second vastly increases the amount of time it takes to consume and respond to writing, since the feedback loop is delayed.
Personally, I do not believe that many people will ever learn to write well; I also don't think it's worthwhile to make them try. I think that organizations, in order share information well internally, should make certain people "writers" who get extract information from their colleagues and convey it to the team. They would be like the secretary in a meeting, but more ubiquitous. This would be part of their job description and KPIs and compensation.
If you're someone who aspires to write well some day, I think it's worth drawing a further distinction. /u/blueyes might agree with this:
"I do not believe that many people will ever learn to write well, unless this person believes learning to write well is worth the effort. If someone doesn't want to learn to write well, it's not worthwhile to make them try."
Which means that if _you_, reader, want to write better, it's worth trying to do so.
If you don't want to write better, well, you've not read this far, so don't worry about it.
edit: grammar x2 It's not easy to write clearly.
And they have to be committed to putting the effort/time into it. Courses are fine--especially for communicating your organization's style and guidelines. But, for the most part, good writers write a lot. (Working with a good editor can help too.)
If someone sees writing as a real chore they're probably not going to get very good at it any more than someone who loathes the sight of a given musical instrument is likely going to become an expert musician.
But these days many companies don't even have testers as a separate position, so... dunno, who else is left, besides managers and developers? Perhaps the janitors could take some extra reponsibility.
Google has tech writers. Works well.
Amazon has a half-day internal course on business writing because it's taken so seriously. Everyone on the corporate side is encouraged to take it. This results in better writing, on average, which lets everyone see the value of good writing.
It's an investment that pays off.
Usually because the underlying ideas are inchoate, so bad writing is often a good diagnostic for muddy thinking.
I think writing is hard for those who's effect can be summed up as individual contributor. The moment you have to work in teams with a head count greater than 1m writing and effective communication become important. It's just people don't really lean into it like programming. They payoff has a slower feedback mechanism.
I think that people can learn some writing with practice (I know because I did). But it's like with everything, if you don't practice, you will never learn. IMHO, this just stresses the importance of having culture where things are written down.
I suggest as a starting point, just write as if you were explaining the subject or code to somebody. Use full sentences, not bullet points.
Onboarding is a good moment for testing a lot of internal documentation. Instead of getting a senior to help set up a new hire, give the newcomer a list of Wiki pages and see if they can set themselves up from it. If they struggle, you'll know what exactly needs fixing.
That's certainly part of the key at Amazon. Documents are written to be _read_ and _used_ in critical decision-making.
If you regularly don't read the documents distributed at the beginning of meetings and then ask questions that are clearly answered in those documents, you will be "profoundly unsuccessful" at Amazon.
(How's that for a euphemism?)
Because not everyone thinks that way things are written. Depending on the person, translating ideas from the 'brain medium' to script can be really difficult.
I love giving presentations with white boards, using visual structures like graphs. I think if companies becomes more flexible about allowing teams to document things in a format that best suits their 'brain medium' then I think a lot more people would be willing to 'write more'. I
I guess that what the article is on about. Writing on its own isn’t enough, the culture must be set top-down to include reading and value added communications as well.
I think a lot of workers who do not have a craft per se just want to coast and pretend to work, and get offended or embarrassed when they encounter serious contributors that make them look useless.
There is an attitude toward the writer of “if you know the topic so well, then just handle ‘it’ and get ‘it’ done”. Unfortunately their idea of “it” has nothing in common with what is described or advocated in the writings.
It feels like writing in a business context can easily enter TLDR territory.
I've often felt like I've had to write walls of text regarding various things, where it feels like there has to be a better more efficient way to transfer information between parties.
Walls of text work well for technical documentation, not so much with other things. You want to be concise, but often you literally cannot be.
Maybe a tool like Loom can be useful, but personally I hate watching a video when I can read instead. Maybe others disagree.
if you want to get fancy, you can work on organizing the document itself so that it's easily scanned for pertienent info (headings, charts, graphs, footnotes, etc.). but as the oft-quoted twain is said to have said: "I didn’t have time to write you a short letter, so I wrote you a long one."
I frequently actually put "TLDR: Whatever-the-point-is" at the top of my presentations/write ups, and then use the paper to actually provide support and pro/cons.
Eventually it came out that a big part of it was:
1. Slow reading skills
2. Slow typing skills
With the result that some people felt they just couldn't keep up in such debates and would thus effectively lose by default. This was frustrating to the group of us that could read, write and type quickly because it was basically a mostly implied request that we stop being good at our jobs. The thing you say about workers "without a craft per se" just rings so true to me.
Organizations can pull it off if enough people do it long enough, and they make heroes of the great writers. You see it in companies that are best in class in talent management.
Well, no. I kind of thought my creative writing classes were a stupid joke at the time, but 15 years after graduating college, it is very clear that storytelling is one of the most effective persuasion techniques I've learned or seen. It's an incredibly effective way of transmitting information - if you can frame your outage post-mortem like a story with a central conflict, rising action, a climax and a resolution, you'll find that it just seems to be repeated and transmitted by itself. Very few people, even engineers want to read a boring timeline that dryly lists what happened in sequential order. Lots of people want to read an adventure starring an engineer who bumbled into a huge conflict and had to fix it before the business imploded.
If you find yourself writing things that no one is reading, try making it more read more like a story. we've all known someone who could take some mundane thing like going on a date and make it interesting with a few storytelling techniques. We might even have a few stories ourselves that we've been crafting over the years. Think about the techniques you use to tell interesting stories - misdirection, suspense, shared context and start applying them to your documents.
Edit: To clarify: Please don't take the advice that structuring your documents to be more like a story means write one of those posts we all groan about constantly that takes a two paragraph report and turns it into a multipage short story. For God's sake don't start your post mortem doc like: "It was a sunny day in March. Birds were chirping. The air was light and airy. As I poured my coffee into my favorite mug that expressed my personality in porcelain, I knew something was amiss. Today was going to be different." Just consider structuring your documents to be more readable and flowing.
I've seen organizations I think would benefit from this kind of role (both in the technical sector, and outside it). Unfortunately, it's been void for a long time-- and one that's not able to be "enabled" by some new technology (meaning that organizations could have been doing it already if they saw value in it). I think the long-standing fact that it remains a void probably means it's an idea that won't ever gain traction.
I'd love to see some case studies or hear anecdotes about businesses that either had-but-eliminated such roles, or businesses that developed such roles.
I've worked in organizations where talented people handle this work adjunct to their "real job". I've been amazed and delighted to be able to refer to documentation in those organizations where it existed. I've also seen those people leave and witnessed the product of their work lay fallow and "rot".
I've seen some documentation come out of more scientific-oriented technical industries (think 'Theory of Operation' texts accompanying old lab instruments) that are just wonderful. I get a real sense of "we have our stuff together" when I see that kind of documentation in a Customer-facing situation, and it gives me a (potentially false, of course) sense that the manufacturer really knows what they're doing if they can bother to produce documentation like that in a Customer-facing scenario. ("Imagine how good their internal documentation must be?") Then again, I'm apparently an odd duck because I get a lot of satisfaction out of creating and using good documentation.
I often use documentation as a gauge for how engaged a company is in making sure their product works in a way that makes sense. I've dropped part manufacturers before because they handed me documentation during evaluation that doesn't make any sense. Like the words are all on the page and someone obviously spent time writing the documentation but they don't make sense, like nobody actually read it.
My bottom line there is that I'm not going to waste my time emailing you every time I need to solve a new problem with your product. I pride myself on being able to respond to questions about how our product works and I refuse to become the middleman between our end customer and your sales engineer.
The first product I dropped for this was a thermal printer. After reading the documentation 3 times front to back I could not figure out what command to send the thing to make it issue a printout. I had to email the manufacturer for an explanation of the most important thing a printer can do.
It is an incredible mental balancing act when you think about it. Your goal is to get some information into someone's head. To do that, you need to actually simulate their brain using yours. You have to think about how that person learns, what they already know, and how to incrementally build up your information in a way that makes sense to them. You have to think about what words and idioms they're familiar with, whether they learn top-down or bottom-up, etc.
In order to get into their mindset, you have to temporarily pretend to not know the thing you are explaining. At the same time, you are explaining it, so you have to simultaneously hold that very same thing in the forefront of your mind.
Now consider that each potential reader learns differently and knows different things so when imagining your audience, you have to do the whole process above in parallel for a number of different imagined audiences.
Doing this well requires a lot of theory of mind skill, and that's something that I think a lot of technical people are not very good at. My experience is that a lot of people who are drawn to tech are that way because they've found it easier to get along with machines because machines "make sense" and are simpler, which to me points to less theory of mind ability.
So very true.
"Theory of mind" is a good term. "Empathy" is another.
https://en.wikipedia.org/wiki/Theory_of_mind
My wife and daughter are on the spectrum and it has been an interesting (and often difficult) experience to spend a lot of time around people whose intuitive theory of mind isn't as strong as a typical person's.
It made me realize how much we take for granted the dedicated brain regions we have for social cognition. For most of us, it's completely effortless to know "Oh, I told her ___ so she'll want ___." We do that processing as automatically as we recognize faces or climb stairs with a cup of coffee in our hands.
But for people on the spectrum, it's like the wetware is reduced, like having bad balance or no sense of direction. They can do the same task deliberately by focusing all of their attention on it, using the general-purpose calculator part of their brain to do a job most of us rely on dedicated hardware for.
Doing that takes a lot out of them. Imagine if every conversation felt like a calculus test. When they don't do that, it manifests itself in all sorts of behaviorally strange ways. There's the classic stuff like unusual affect and eye contact. But the one I notice a lot now that I'm attuned to it is pronouns. They will often use a pronoun to refer to a noun they've never introduced, because they are already thinking of that noun and didn't notice that they never mentioned it explicitly.
Brains are weird.
but it is drastically different in how it's interpreted by that other actor: computers are (designed to be) fairly rigid in interpretation (the frontier of that not being so is fascinating but in its infancy), so that there's little-to-no variance in the output. people are completely flexible in comparison. inputs can generate a wide range of outputs, and there's little control over that range within the writing itself. that seems to frustrate many coders.
even the purpose can vary. coding is generally imperative in nature: do what i tell you to do. writing is generally persuasive (here's what i think, why i think it, and why you should think it too), since it's hard to force the imperative.
writing is necessarily harder than coding, because the target has so much greater complexity.
That's a great observation. A bit of a tangent, but I enjoy writing code with a tight feedback loop. Either with a debugger, a set of unit tests.
With writing, the feedback loop is not there. It's not clear whether the message achieves the desired effect.
Framing writing this way, explains why it's such a challenging activity. At least in my mind.
I spend a lot of time rereading my code imagining I'm someone else who's never seen it before. Not sure everyone does.
Yes, I like to tell people that English is a programming language with no official spec and a billion partially incompatible compilers.
The single most important thing, in my opinion, that these folks are missing is they do not write with an audience in mind.
Our manager's boss doesn't need long technical emails.
"javascript|ruby|python developers" should not need documentation on how "javascript|ruby|python" themselves or their standard libraries work. There is documentation for that already, but I have been asked to document such things.
Wikis are riddled with problems. They become out of date quickly. They need a librarian over time to organize the content in a way that's meaningful. There's also no "habit loop" to encourage people to regularly contribute content.
Right now, wikis are a tax on the most productive people in a company. If someone asks you the same question over and over, you will eventually document it to share.
At my company (https://www.friday.app/) we've found a way to get people to regularly communicate asynchronously via regular updates like daily standups or weekly status reports. It's more like a work journal vs. a file cabinet.
Incidentally, the past 30 years have precisely seen the disappearance, but in very select types of businesses, of secretary/assistant/aide roles.
When the above isn't the case, then you have the people who are too lazy: they cannot be bothered to simply read over to themselves what they've written even one time. And when they aren't merely lazy, then they're simply too dull-witted to understand the need for this.
Lastly, you have the people -- perhaps overrepresented in tech -- who suffer from something like an underdeveloped theory of mind. On some fundamental level, they don't understand that what is in their mind is not necessarily in the mind of the reader; and so they lack Clue Number One as to how to establish context.
Writing isn't difficult. People are difficult.
I've invested a great deal of effort in writing documents in the past only to realize that very few co-workers were taking the time to read what I'd written.
There are workarounds for this. The most famous I can think of is the Amazon culture where each meeting starts with 10 minutes of quiet reading, to ensure everyone is on the same page.
I imagine it's part of a writing culture though. Once people understand that an organization values writing, they'll take the time to read.
can never find it again...
benefits: versioning, code review of docs, portability, plaintext search tools, docs show up while grepping for code, can change code and docs in same commit, git blame, you can "guess" where documentation for a service lives if you know it's location in the repo.
downsides: not everyone enjoys learning markdown syntax, it's a skill orthogonal to communication. eng is a gatekeeper for changes to documentation, i.e. product can't go through it and fix typos. our code review tool does not have as good inline comment-discussion UX as G Docs (biggest one).
You can even write unit tests that verify that certain things are mentioned in the documentation: https://simonwillison.net/2018/Jul/28/documentation-unit-tes...
Totally agree, code review is a huge plus for many reasons.
If your company/project has a build graph (bazel, pants etc), you can even make the source file a dependency of the document, so whenever the source file changes, it's trivial to generate an automated "hey don't forget to update <doc> if it's relevant to this change".
Looks like a thin wrapper around the confluence API and a homebrewed md to html converter, that supports inter-document links. Looks like most of the code was written by folks at Twitter.
Personally, I'd advocate for using pandoc (https://pandoc.org/) unless a custom solution like this makes sense and you have the eng resources to maintain/support it.
Pandoc will give you a pretty sensible html document by default, and with some fine-tuning you can make the outputs look pretty great.
Pandoc also generates beautiful and customizable latex-powered pdfs. We have a policy of publishing those to G Drive every minor version.
1. Having a "doc of docs" for each team - a document (Google Doc, wiki page, whatever) that acts as an index for all of the other documentation. If anyone asks "where's the documentation for X?" the answer should be "It's in the doc-of-docs. And if it isn't, it's your job to find it and put a link to it in the doc-of-docs".
2. Get a good search engine! I built a search engine for work that indexed documentation content from 8 different sources, because building a single search index was easier than convincing dozens of teams to switch the documentation solution they were using. I used an improved variant of the technique I described in https://24ways.org/2018/fast-autocomplete-search-for-your-we...
Maybe even some social features, with a decay rate. So teammates recently tagging things as "helpful!" could nudge me to pay attention.
Any additional signal to help noobs like me while foraging.
That way a team could be alerted if their documentation was due-for-review. One person gets assigned a task to review it. They look through it, update it if necessary, and either way put a "last reviewed by X on date Y" tag on it so people who read it can tell that it's still relevant.
Everything needs a default automatic TTL, just like renewable leases.
As an American, I've never heard of this, and can't even imagine it.
Is it literally a quiet-read time where everyone just sits there silently reading a shared doc? Or is it what Ive seen happen in a lot of companies where someone projects the doc, and walks through it, reading/summarizing it aloud to attendees. I like to call that activity "executive storytime", since it's often underlings reading status reports to execs.
Some reasons why (loosely paraphrasing internal guidance on how to run meetings and why writing culture matters):
- PowerPoints are lazy/evil, and not good formats for conveying complex ideas; by nature, PPT's encourage shallow thinking, and is thus antithetical to the goal of having rigorous analysis/deep-thinking in making complex tech/business decisions
- Docs should stand on their own, without needing to be presented or walked-through by a person; forcing you to explain your ideas and support them in such a way that any sufficiently motivated reader can follow along and work out what they mean on their own, is again a way to encourage you to be rigorous and thorough (but limiting you to 6-pager format, for brevity)
- Writing long-form paragraphs and full sentences forces you to take time to refine your ideas
- Forcing people to take time to digest the doc first, gives everyone a chance to take notes and formulate ideas/responses to the info/arguments presented; this saves a lot of time as compared to, walking through a doc/slides for the first time, and having a roomful of people encounter those ideas for the first time and to ask questions in real time as they encounter them... reading the doc should hopefully already address the most common questions/critiques, and so you can spend more time on 2nd/3rd-order more advanced decisions or arguments
If you try talking during this time, you will get lots of dirty looks (and then probably be fired if you keep it up).
Instead, using a written document absolutely forces the presenter/writer to have clarity in thought and it absolutely requires that they "cut the bullshit" and get to the point – what matters and what doesn't matter.
These kinds of meetings will derail if the writer hasn't fully fleshed out their ideas or even if the document is missing important structure ... the purpose of the document, what the author is trying to get out of the meeting ("what is the success criteria for the document or meeting?"), what's in scope, if it's a technical document then clarity in functional requirements, non-functional requirements/constraints, options/alternatives, trade offs, and so on.
In my honest opinion, the document driven meetings provide Amazon a competitive advantage.
Definitely. I do see a lot of value in understanding what different teams in my org are working on and am excited to read about it; I write in a manner that caters to that kind of audience, to present information in a no-frills, easy to consume manner so the readers don't feel like they've wasted any time.
A good culture of writing is very important to scale; as companies grow, the tail doesn't know what the head is doing. I won't harp on some imagined "waste" that can be saved by better communication; instead better communication simply makes everyone feel like they're on the same page and suggest/contribute to the org's growth. That itself is a big deal.
In orgs where the muscle for long-form reading has atrophied (for the above reasons), you can try to write document to account for a weak long-form-reading muscle.
Begin your document with an abstract TLDR and ToC, open each top-level section with a TLDR paragraph, and provide pointers that imply the TLDR assertions are supported by evidence (i.e. internal links to the relevant section).
The key to good TLDR-writing is terse, in-order parsable sentences, and short paragraphs (one sentence, maybe two per paragraph), with tasteful font-weight choices. I'd discourage using font-weight outside of TLDR's, except maybe to highlight keywords.
I think wikipedia is a glowing example of what documentation should be. Some pages are huge (e.g. https://en.wikipedia.org/wiki/World_War_II), but each section is dense, and filled with links to more detailed pages. To find the specific answer to some question, you often only need to navigate the table of contents and two or three sections/links. And yet, the pages can also be read straight-through. Writing like this is a hard skill to earn, but it's reward is probably a culture of reading.
I suspect however I would put it in the category of 'I saw a tweet about the film of the book' for descending levels of nuance (but increasing levels of getting the point across)
I spent 40 hours making a 18 minute video. If that's run at 2x, that's a 9 minute video. So that's 266:1 ratio.
And I made the video because some people read and some people watch.
Again the video was well recieved, it was however probbably not worth the time. I only did it because I was remote with bad internet so it was how I could be successful at that time.
It would be an interesting experiment to visibly prepend the search queries each employee had done before asking a question to their actual question, in order to discourage asking questions before searching for the answer. You said you had built your own search solution, so clearly you could wire up a form that actually does this.
This. Every time you send a private message is Slack or send an email to just one other person, it's like taking a $100 bill and lighting it on fire.
Just because only one other person needs that information right now doesn't mean that in a couple years some new hire won't spend six months just staring at their monitor and not writing code because they can't figure out wtf is going on.
The problem with team chat is that it has very low signal to noise ratio, which makes it hard to find structured info.
Don't get me wrong Slack is super useful, and I use it to communicate with my team all the time. But I don't think searching old chat messages is a good experience at all and I don't even think it even really qualifies as a solution to the concept in this article.
To me a culture of written communication involves actually spending the necessary time to write down explanatory copy that helps inform other people. That could be things like comments in code, annotations or instructions for a commonly used document, detailed proposal or recommendation memos, FAQ's, guides to how processes work, and so on.
There's this theory that this information already exists and the goal is to capture it. I'm not so sure, my suspicion is that you have to put in work to create it if you want to see real results.
Sure, you can dump a ton of stuff into the public Slack channel, but it turns into a mess of wrong stuff, disjointed ideas, hypothetical chatter, and unanswered questions.
People are still going to ask someone else rather than trying to go through that hairball.
My team probably has half our knowledge in our general dev chat on Teams. Nobody even tried to use that.
Same, my team probably has most of our knowledge buried among the various document repos and wikis, but it's all at varying levels of out of date between a few days and a few years.
The core of the problem, I think, is that the digesting and organizing of information has to happen somewhere. If you want to make it easy to dump info for the future, then you make it low friction to write it, but because nobody's taking time to organize it, it's going to be a pain for future readers to glean useful insight from it. On the other hand, if you require the writers to organize the info and occasionally update obsolete articles, it'll be much more useful for future readers, but it'll be much harder to contribute info in the first place.
IMO the next big win on this problem will be whenever someone comes up with an actually good search engine to organize this sort of team info. Stack Overflow did a great job with public info by relying on Google for search, but there isn't really an equivalent for internal info. If we have this, we can rely a bit more on automation to reduce the amount of organizing the writers need to do in order to produce usable documentation.
Instead, make sure you have a good onboarding procedure. Documentation is important, but categorize it in e.g. a wiki with a solid landing page, so that new hires can get up to speed quickly on the one hand, and know where to find information relevant to what they need to know on the other.
I've been at my current company for nearly six months now and I feel like I've barely scratched the surface in the application (which was started eight years ago, but built on top of two more decades of domain specific knowledge and platforms).
No, just that they'll search for whatever information they need to do their jobs within the company's archived email. The nice thing about email is that each message is dated and comes with the author and the author's contact info, so you know exactly who to ask if they're still at the company. (And if they're not at the company, you can ask if you're allowed to contact them depending on the context, or at least figure out who they worked with.)
Maybe, but with a public channel, it's a stack of $100 bills, for the time of everyone who doesn't need it now and won't recall it or be able to find it when they do.
“Spam everything to the public channel” is the equivalent of “send everything you find interesting to the All Staff email distribution list".
There's good ways of preserving information that multiple people on a team are going to need at different points of time in the future, but posting them to a public Slack channel is pretty far from the target.
A team wiki is among the many better options.
Yes, a wiki is very much imperfect.
It's still much better than a public Slack channel, which faces the same limits plus additional ones as it cannot represent the knowledge of big picture structure held by the people feeding it.
Wikis are generally useless unless you have people whose job responsibilities explicitly include creating content for them and keeping them up-to-date. In my experience, if you have your PMs do this then each PM can cover 8 - 12 developers. Whereas if your PMs are just creating and pointing tickets but not also spending a good percentage of their time on longterm documentation, they can cover more like 12 - 16 developers.
Well maintained wikis are fantastic, but you almost never find them because for even a mid-size startup that costs hundreds of thousands or millions of dollars per year. That's the reason for public mailing lists and other email archival products, because you're getting most of the value a well-maintained wiki but with mainly only the nominal cost of paying for the software to keep it running.
I've thought a lot about this (obviously, given FWD:Everyone is in this space), and figured out the actual reason why email is so much better than Slack for knowledge retention; it's because with email you're forced to create the metadata before having the discussion, and then the discussion keeps going until people no longer have anything to say that matches the metadata -- subject, participants, visibility level, etc. (Discussions occasionally go off the rails, but less than 5% of the time as long as the organization provides some basic guidance on expectations for communication.) This metadata is key though because not only does it help you find what you need to do your job, but it helps you figure out what you don't need to read, which is perhaps even more important.
Whereas with Slack you just start talking, and their software tries to figure out what you were talking about after the fact. But despite having an AI team working on this and having invested millions and millions of dollars into the problem, their software doesn't really work at all, most likely because the problem is basically impossible to do a good job of solving from a computer science perspective.
edit: Obligatory self-promotional link: https://www.fwdeveryone.com
Interesting example, appreciated!
Let me try to improve it:
it's like taking an envelope that might or might not contain an $100 bill and lighting it on fire.
Not everything is useful, but we don't know until later.
Also, the company doesn't get that $100 bill right away, only if they can dig it out 2 years later.
Still, good example.
There's a fundamental tradeoff between the percentage of communication that gets captured and the usefulness of search. We take the position that email threads shouldn't be archived unless someone flags them to be saved, on the assumption that for most employees there are only a couple dozen (if that) really important email threads being created per year.
But the value preserving this knowledge can be extremely high. E.g. most SaaS startups are built in part by wiring together a few third-party APIs, and the process of partnering and integrating with those third parties often involves email threads with hundreds of messages back and forth. If those threads get lost because the person leaves the company then that becomes extremely problematic.
This probably differs from team to team
I'm more or less sure I have been saved more than once by people who didn't tidy up after themselves and so left information behind even when they planned to remove it. Sometimes the reason seemed to be that people didn't care, on other cases it seemed like a way to try to keep knowledge for themselves.
In those cases we would have been much better off if the default wasn't one-to-one. Not because they wouldn't have tried to circumvent it but because it would slip up more often.
(Of course the real problem on such places is the culture though.)
At GitLab, we don't just document to document. Instead, we recommend a "handbook-first" approach, which we outline here in our public handbook: https://about.gitlab.com/company/culture/all-remote/handbook...
We're also articulate about what we expect in terms of writing style guidelines, part of our Communications handbook: https://about.gitlab.com/handbook/communication/#writing-sty...
I see that the handbook is mostly focused on company level procedures and "What we do". Doe GitLab folow similar principles for documenting code? E.g. Update the documentation for the design before writing code?
- Most of the dev are not trained for that. They're trained for finding shortcuts (Google, SO), rushing the deadline and fix the code with any solution they can find. People tend to follow the easy path (fix and forget) rather take time to write good docs (code comment, commit message, wiki, ...)
- Some people have good writing skills, some have good technical skills. The ones who are good at both are rare. So some time the docs are confusing, misleading.
- We're lacking good tooling for writing docs. At my work, people prefer to write on Confluence for its inline-comment feature (before, they write in Google docs). But Confluence (and Google docs), IMO, are terrible editors for technical heavy docs and they can't work offline, don't have desktop, can't be used with external editor (I'm a die hard vim fan). Another example: tools for drawing diagram. The plain text solutions (PlainUML, mermaid) I've tried so far don't work well for big diagrams. The non plain text solutions can't be tracked in git, thus defeat the point of single source trust.
I believe if someone can build a product solve my points on tooling, their product will beat Confluence easily. I don't have any ideas to fix the other 2 points, though.
In my experience this is not the case: good programmers are typically good writers. I think it’s due to clarity of organization and of understanding “the problem to be solved”
Anecdotal, but in my limited experience those with poor writing skills are also poor at writing software.
Typically those who have put in the effort to design and understand their solution are also pretty good at communicating their changes.
The people who rush to get things done quickly and have trouble communicating their changes tend to (in my experience) not really understand what they are doing themselves. More often than not in my experience this group of developers mostly implement ad-hoc solutions that eventually have to be fixed up by the "good at communicating" group later.
Perhaps improving speech-to-text programs will help a lot? Maybe they can record what they want to document in a lecture-style way. Give them a white board or paper, set them up with a good microphone, and get a program that records their voice to a video / mp3 file. Then process their lecture through a speech-to-text program and have another team member format it to match the wiki. That way all the other team members are doing is light editing of an existing document.
Now that doesn't fix the issue of the dyslexic team member having trouble reading. Maybe they can use screen readers like JAWS to quickly have knowledge bases read to them? That way it is no different than an in-person phone call?
You'll still have those who use the "can we get on a call and discuss" trick so that no decision or todo item for them is seen in a public channel.
There will be those why try to kill a conversation in a channel by replying in a thread.
Often you'll see the thread reply too when its the poor employees answering a question hours/days later and then they'll point to it as giving $teammate all the info they need.
And the ever-present "oh, its in the wiki/knowledgebase/faq/whatever" but links are never sent, nor is anything ever actually there.
All in all it a different medium, but most of the same kind of team dysfunctions continue to exist just fine, and if anything it is tougher to spot them.
Agree x1000 with this point, with emphasis on the point about readers. The probability that someone will write down an important piece of information (and will do it well) is proportional to their perception of the benefit from doing so. If the would-be author thinks nobody would read it, they won't write it down in the first place. If they think team members will find it and read it 1,000 times in the next 3 months, then they're very likely to write it down.
> I believe it has to be easy for people to write a document without having to worry too much about where to put it. Therefore, I believe it's better to have a tool with good search functionality rather than investing in having a perfect information architecture. In the latter case, we're putting up extra roadblocks for the writer, because then they'll need to spend extra time figuring out where to put their writing in the first place.
To make this work, I think you need to designate certain documents and locations as sources of truth. If any random Google Doc that someone drafts can be considered a source of truth, then gathering the "canonical" information about any topic ("what's all the customer feedback from Acme Corp?") becomes extremely difficult, especially to newer team members who haven't fully internalized the communication practices yet.
Here's our handbook page that describes what has worked for us (at Sourcegraph): https://about.sourcegraph.com/handbook/communication#sources.... Only very specific Google Docs are sources of truth; all others are just ephemeral scratchpads.
Naturally, these have been called "bibles": Unix Bible, Linux Bible, Linux Command Line and Shell Scripting Bible, etc.
I encouraged the team to write blog posts on anything they didn't know and took time to figure out, or if they stepped through a process for the first time that wasn't already documented, or ran into some dev VM issue that they fixed. Crucially, I made clear that a "blog post" could be as little as 1 paragraph and a code snippet, it didn't have to be big.
Blogging had the following advantages: 1. No need to think of "where to put this in the wiki" – just write it in the blog & if we decide to put it in wiki we can move it later 2. Blog posts naturally "go away" over time, so it's clear that something written a year ago might not be current 3. It was regular writing practice for everyone on the team 4. It allowed others on the team to learn from someone's experience & improved information sharing & collaboration 5. If I figured out how to solve some issue and someone else ran into it, I could say "go look at this blog post" 6. When we had a new person join the team, during orientation I'd say "read the last 6 months of blog posts (might take an hour or two) and that helps them understand the team culture & norms way faster than they would otherwise 7. It gave me (team lead) more visibility into what people were doing & allowed me to step in and help when appropriate. 8. It "forced" people to structure their thinking & clearly define the problem they were facing and the solution 9. It allowed people to "get credit for" work that might otherwise be invisible (e.g. spending a day debugging some webpack issue or researching options for an upcoming feature).
Over a year or so this became a major part of our team's practices, and there were countless times when someone on or off our team would say "how do I do X" or "why did you chose to do Y" and I'd say "good question! Go read this blog post."
Currently I have google suite instead of confluence and I seriously miss the blog feature. If someone knows a good, small, private (not public but easy to share internally) "team blog" platform, let me know. (I tried blogger but sharing is a pain in the butt.)
If instead you used a wiki (e.g. MediaWiki), with the convention that all blog articles are prefixed by "YYYY-MM-DD USERNAME" and linked from the top of the "All Articles" page, what functionality you want would be missing?
I do like the date metadata & sorting from a blog like wordpress or confluence: automatic grouping by year, automatic ordering, as well as features like tags etc.
Writing documentation has a barrier to entry: what if I'm wrong? What if others on my team disagree with how I'm documenting this? What if I'm on the hook for maintaining this documentation for the rest of my career? Or what if the documentation goes out-of-date and ends up causing more harm than good?
Blogs solve all of these. If I post an internal blog about how something works it has three things that fix this:
1. It has a date on it. It's clear that it may not still be up-to-date in a few years time.
2. It has my name on it. It's clear that this is my opinion / my experience at the time, not the official internal position of the company
3. It's a "blog", not documentation - so it's OK if it's incomplete or inaccurate.
I ran an internal personal blog at my last employer for this reason - using Confluence because we already had it, so I didn't need to introduce a new tool.
I didn't quite manage to make it stick as a habit for other engineers - I'd have liked to invest more effort in that.
- We create living documents / whiteboards on Miro (formally Realtime Board) that relate to the features we're working on. Things like pictures, architecture diagrams, draft db schemas. All at WIP stage.
- When we need to create communications (like requests for comment, demos etc) we record a short video using Loom. The video usually centres round some area of the whiteboard or in the IDE.
- We post this both on a notion page and in slack (using a public channel as to article suggests), tagging those that need to know or would find interesting. Keeping a long list of previous videos in notion helps find useful data later.
I think the low barrier to entry for recording video over the top of documentation thats "just good enough" to get the idea across has lead to universal uptake across our team. It's also easy to slot in reviewing these videos and responding during natural breaks in flow.
For more critical areas of the code / operations we document more formally towards the end of a feature development cycle.
How does this compare to livecoding on a streaming platform?
We still hop on a quick Zoom 1:1 if we can't find the words to discuss over text.
Email is the quintessential async tool. Slack isn't really even that async -- people still expect quick responses (it somehow has that expectation built-in)
For individual contributors, sync meetings really disrupt the flow of the day. Worse are meetings that don't respect your time zone -- either too early in the morning or too late at night.
People don't realize how disruptive it is when someone says "let's jump on a call" for every single little thing. I much prefer them to just "send me an email".
Sometimes sync meetings are more efficient, especially for complex topics or on topics requiring a live demo -- but I find having a sync meeting after an email thread much more effective, because then folks have had a chance to engage with the material.
In that vein, this piece is missing one thing. It is inherently easier to write something private than to write something shared.
Think of how often you jot things down in Apple Notes, Sublime, etc. as opposed to in your shared space with your team.
A culture of written communication starts with personal (un-shared) notes.
I'm one of the creators of bytebase.io, a notes app that helps people write low-friction, private notes and quickly share with teammates when relevant.
One day, I discovered that our document identifier issuing system (yes, we had one!) could tell you how many docs had been registered by a particular teams in a given time period. This led me to the finding that our department created a new document something like every 58 minutes of a working year! We weren't a software project group, we were in fact a document authoring function that also emitted software and research as a side effect. That observation got some traction with management, and I was funded to develop some how-to-write guidelines for document authors. Bid teams were particularly interested because the cost of document production in bid development often fell directly to the company, not to the eventual customers.
In addition to providing a basic 'house' style for authors, the guidelines also highlighted the importance of easy-to-use doc templates and training for lead authors (e.g. those collating docs produced by multiple people, sometimes by sub-contractors).
That makes it technically available, but also less accessible than a paper Encyclopedia Britannica. Are people actually going to try and search through the Slack channel for a solution or are they going to continue asking their co-worker in a private chat?
This is exactly the reason why we build Emvi [1]. I've worked with a lot of different tools and none of them really encouraged people to write stuff down. Not because they weren't easy to get started with, or the editor was bad. I feel lost in a big hierarchical structure and was unsure where to put things. I always had to ask someone where to put a new article or where to find an existing piece of information. So a powerful search and focus on writing instead of organizing folders helps a lot. It still requires discipline and if you want a team to write down as much as possible, you need to build the culture. But if you don't feel you're doing something "wrong" in the first place lowers the barrier. Once you have reached the critical mass of articles and put some tags on them, you will start to see connections automatically. Emvi allows you connect everything via mentions (start typing an @).
Check out our upcoming user interface [2], it will take this approach even futher.
[2] https://emvi.com/blog/a-new-experimental-user-interface-QMZg...
...including writing about COVID-19. :) Sorry, couldn’t help cracking a joke after being exposed to so many memes.
> I believe this is the wrong approach though. Context matters. In a team of individual contributors, it’s crucial to share ideas early, to iterate and collaborate on them. Not everyone will have the same level of writing skills. Improving it can take a long time. Lower the barrier, encourage more writing, and people will get more practice.
This requires a feedback loop. It’s like writing a program and being satisfied with it yourself, and then someone points to a bug or does a code review and points to issues or areas for improvement. Just lowering the barrier to write without a respectful feedback loop isn’t going to do anyone any good. There are too many blind spots that writers themselves cannot discover.
> Where you should enforce high-quality writing is broad or upwards communication, because there clarity is more important than speed and ideation. Here too, it’s important to keep in mind that good writing takes time.
Yes, it does take time. But being able to write well not only shows the person’s ability to write, but also clarity in thought and an ability to communicate thoughts to others. In a world where most of the communication, even before COVID-19, is in written form, it’s important to treat every piece that one writes with care. Mastering a language may not be easy. But showing some care while writing is within the reach of many people who need to convey their thoughts to others.
Everyone here seems to be conflating good written communication with documentation, but good written communication has happened via a mailing list for decades. Mailing lists provide the many to many interface of a meeting or IRC but unlike those they happen asynchronously, handle many topics, many users and are searchable. Async especially is the key because it allows responses to be informed and well thought out.
This is a proven model in our industry especially, for decades it's been the primary communication medium for large international OSS projects built by teams of people that never met face to face. Imagine where linux would be if Linus was spending his time waking up at 3AM for a face to face with the team in New Zealand and updating wiki articles.
I like writing. I've been writing all my life.
In the last couple of years, I have taken to building a "personal brand," by writing about the way that I design and develop software.
It's been really good for me. I find that it helps me to consolidate and focus my thinking. It also helps me to feel accountable, and I'm a big believer in accountability.
If I write something, it had better be true and accurate.
I often review everything that I write in public, and make even small grammatical corrections (I miss one, every now and then, though).
I also like reading. I devour books; usually escapist fiction. The first non-child book I ever read was Where Eagles Dare, by Alistair MacLean. I started reading because I lived in Africa, and the TV sucked.
YouTube is the most important asset on the web.
In fact, we’d be better off if most “thoughts” weren’t committed to virtual paper.
In the beginning you want a medium that malleable, nuanced, high bandwidth. Speech. Visual emotion. Voice inflection. How we’ve evolved.
It’s in those moments where ideas are challenged sbd change form quickly.
Then once they’re a bit more solidified, take a pass at writing. Which adds further clarity.
I think eventually we find a place again for voice and video for remote work. Something that isn’t a huge production but still async.
Yac or Loom look really promising in this area.
Some people learn best from video content. Others (like myself) would MUCH rather scan through a written tutorial than sit through a 15 minute video (though thankfully I can watch YouTube at 2x speed).
Some people really benefit from interactive exercises. Others find them to be a waste of time.
A big challenge in creating a good internal learning culture at a company is working out how to best address those different learning styles.
I agree with all the child comments questioning whether you can or should inculcate writing skills — they're only one path to success. People with passable or subpar writing skills can find other paths.
I've met more than a few engineers that in meetings don't tend to speak up and in chat channels mostly don't engage. Chat channels tend to be dominated by the same people that are also dominating meetings. This is not necessarily a good thing.
For better or for worse, this causes side channels to pop up and this is where most of the discussion happens. This is a problem because it by design excludes people. But it's needed because you can't speak freely in a channel where everybody in the company listens in, including management, individuals you don't get along with, etc. Pretending this is not a problem is not helpful.
In OSS projects, there's a pattern of frequent contributors to be disciplined about how they use communication tools. IRC historically is the place where people discuss in an unmoderated forum. It's noisy and chaotic and often not pretty. But it's not necessarily there for documenting decisions. That's what issue trackers or mailing lists are for. Those tend to have a narrower scope of what is on and off topic.
Translating chats into actionable items, or documenting outcomes of discussions is the key thing to do. The larger the project, the more obvious this need.
In a corporate setting, the tools for this are comparatively poor and not that good for facilitating asynchronous communication. E.g. Atlassian's tools are pretty popular but not great for async stuff. IMHO Jira is slow to interact with and this obstructs effective communication. It's notifications, default settings, etc. are basically completely wrong and counterproductive. Absolutely everything requires multiple mouse clicks. IMHO Github issues is vastly easier to deal with for engineers; it's also easier to refer to commits and pull requests there. And with github actions integrated, you also get insight into the status of CI. Likewise conflucence is a PITA to use compared to managing markdown files in a git repository or co-authoring a document on Google docs. Slack is nice but way too noisy for communicating things unless you have read only channels that are used for things like announcements.
I’ve always been a stickler for clear writing, but recently I decided I will settle for effective communication of any form.
If communication is only encouraged as a tool to transfer the needs of an executive to teams and then individual contributors, it will wither and die.
To improve written communication, you must improve the culture first.
As with all things, there are no absolutes. Don't blame tools for broken process. End of the day, you need to have a common process to debate, make, and memorialize decisions.
If you want to type, please do it in an IDE.