I love this topic! A couple of unconnected thoughts on it:
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.
> 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.
> 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).
Secretaries were and still are generic, unspecialised workers. I think the 'team librarian' idea assumes some level of technical knowledge.
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.
> Secretaries were and still are generic, unspecialised workers.
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.
Another insidious motive for the avoidance of writing: keeping things off the record.
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.
I used to work with an IT person that Absolutely. Would. Not. Put. It. In. Writing.
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.
The standard tactic in such situations is to send another email. "Hey Gerald, thanks for coming to see me. My understanding of your points was X, Y and Z. Let me know if that's wrong".
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.
This guy dealt with that, simply by not replying or acknowledging the email, then claiming "That's not what I agreed to." His boss would support him. It worked, most of the time.
Scott Adams once wrote a book: "The Way of the Weasel." It has some techniques in there that are remarkably familiar.
For sure, but sometimes the boss has a boss. Or takes you to HR. Or some other thing you didn't think of in advance. In all these cases it didn't matter tactically, but it did strategically.
I would love to do this kind of work. Aside from a general passion for writing and editing, I enjoy describing problems, characterizing existing solutions' strengths and weaknesses, writing docs and user instructions, organizing information, etc. I'm a good enough developer to build useful tools and work with more senior engineers, and my favorite part of working in scientific research was being a force-multiplier and hindrance-destroyer so subject-matter experts could focus on using their skills.
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 don't know if you've ever considered a position in pharma or biotech, but clinical research has a career like this called Clinical Trial Associate, and their entire job is to organize information, prepare instructions and documents for the research sites, organize and run the eTMF aka "Trial Master File" and other documentation tasks. Our CTAs start at 95k and make up to 125 for senior level. From there onwards you have a good career path of Clinical Trial Manager and leadership- might want to check into it.
I appreciate the tip. As it happens, my last full-time position was in clinical (computational linguistics) research.
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.
Yeah same honestly. I don’t like producing a ton of code, but I’m good with tech and more complicated stuff like memory management. I think I could be very helpful just answering folks questions - I feel that’s mostly what I do anyways.
My job is exactly like what you describe. In a way, I am the executive branch of management. I don't decide what needs to be done or how it needs to be done. I just make sure it gets done.
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, to me, defines the heart of a true DevOps mindset. It's not easy to find this role defined as such, though, and you'll often find yourself fighting to carve it out of a more simplistic definition (i.e. automate stuff) at most organizations if you choose to pursue the path.
> I'd love to experiment with hiring someone whose primary accountability is answering everyone else's questions, not generating output
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.
>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.
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.
If after “resolving” something you can’t actually write down what was accomplished, nothing was resolved.
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.
On my last team that would result in a JIRA ticket containing the details so approach Y was documented and the reasons behind it were recorded. Then the ticket is assigned to Person X and they go ahead with the work.
I would go as far as to argue that this isn't just your being "bad with" async but rather an inherent drawback of async: namely that it requires way more context switching!
Async requires more deliberate planning to avoid context more frequent switching. Time blocking is your friend and with asynchronous communication you have more freedom to time block. You can create a maker's schedule for yourself rather than the manager's schedule where your day is an endless string of meetings.
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.
I would say often times this does and should lie with the senior folks on a team. They're the ones who must be able to communicate well since their impact should be broader, perhaps even outside the team. And they should be scaling the team with their own knowledge and experience. I know it's a little different than what you're getting at but i think one person can do both.
> 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.
If I remember rightly, this is actually one of the core ideas in The Mythical Man Month.
There is a librarian in the mythical man-month, and there are documentation writers and secretaries. All crucial to successful team - the librarian AFAIK was more about keeping stock of code (but would also fit with design docs), technical writers were crucial in transforming developer's ramblings into proper documentation, secretaries helped keep everything running smoothly, etc.
> 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.
If you want to have ok documentation, making everyone do it, can work. If you want to have great documentation, it's hard.
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.
Half of the reason I want to run my own company is build this culture and hire that role. The team librarian position is probably the single best value for money multiplier possible on team productivity and yet almost no one wants to invest in it.
That's even before we get into second order effects of building new pathways into technology work.
> 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
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.
> 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.
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.
> 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.
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
Posts like this are published with regularity. And like all things that must be said again and again ("stay off the grass", "we're in this together"), we can assume the opposite somehow true: Most teams do not write much or do not write well.
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.
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.
great point. i don't generally buy the argument that coding is drastically different from writing, insofar as it's laying out symbols in a way that can be understood (and followed) by another actor. that's a technical skill that's fairly transferable between the two.
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.
> 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.
Yes, I like to tell people that English is a programming language with no official spec and a billion partially incompatible compilers.
> i don't generally buy the argument that coding is drastically different from writing, insofar as it's laying out symbols in a way that can be understood (and followed) by another actor. that's a technical skill that's fairly transferable between the two
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.
yes, another good point. you have to be your own feedback loop, simulating as many other minds in your head as you can, as @munificent laid out. it seems that proofreaders and editors came about to help in that regard.
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.
Yep. I’ve been on a few remote teams where I write a lot (in plain language too), and have found that if my audience is non-technical management that they simply don’t read it. Decisions continue to be made on their gut whims despite access to the critical information.
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.
Absolutely this. I've actually seen company founders get frustrated and upset at waking up and having Slack channels filled with complex debate that happened over night (even when they didn't need to read it). Not for any clearly articulated reason, just a vague feeling that people shouldn't do that.
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.
> I’ve been on a few remote teams where I write a lot (in plain language too), and have found that if my audience is non-technical management that they simply don’t read it. Decisions continue to be made on their gut whims despite access to the critical information.
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.
that's easily solved by a summary at the beginning of the document, laying out the premise, the conlusions, and a short thread connecting the two.
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."
> It feels like writing in a business context can easily enter TLDR territory.
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.
Most writing is written for the purpose of being filed, not read. It's as simple as that - it takes exponentially more work to write something that you intend and want people to read. Most engineers just cannot be bothered with such a menial "soft" skill - the information should be interesting enough, right?
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.
> 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.
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.
Do they have any materials available to the public? I vaguely remember reading about their approach to meetings (written agenda with context which everyone must read prior etc. )
How often do you use the word inchoate when speaking?
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.
Besides the fact that most people are not all that great at writing, it is also often not to their advantage to write at all. At worst, they are in an organisation that will offshore their job at the earliest moment it seems they are easily replaced. In the more benign and common case, writing a lot is not directly detrimental to their career but it will not be that advantageous either. Written documentation is by nature usually technical in nature and therefore not often read or noticed by management. It does however take a lot of time to write, time which can not be spent on the parts of your job that get measured with KPIs or OKRs or whatever. This means that spending a lot of time on good documentation will make you "less productive" according to the measurements you are graded on for career advancement. I wonder how that would fare if you have a separate "documentation secretary", since helping those understand the code you just wrote has the same drawbacks as working on the documentation yourself.
I imagine one could be part-tester and part-writer. Both the tester and the documentation writer need to understand how the application works (at least from user perspective). The work for testers comes in waves; they could work on documentation between the waves. It could even make sense to highlight in user documentation, which parts are already done and tested, and which are still missing.
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.
> I wonder how that would fare if you have a separate "documentation secretary", since helping those understand the code you just wrote has the same drawbacks as working on the documentation yourself.
This is a great point. The issue is that the current best practice advice is to use a wiki.
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.
You don't have to be Stephen King to write clear technical documentation for your fellow teammates.
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.
I think it's also important to have a culture of reading, not just writing. Otherewise, nobody will ever know if the writing is any good. It's like with backups - you don't actually have one until you've successfully restored your system from it.
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.
>> I think it's also important to have a culture of reading, not just writing.
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.
> 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.
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.
>If someone doesn't want to learn to write well, it's not worthwhile to make them try.
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.
There’s a distinction between learning to write well at length or often — and learning to write well enough for clear, concise communication. The former is not something everyone needs or values. The latter is one everyone should work on, especially now that we are all communicating via chat, email, comments, social posts, and other written methods. Effectively communicating your thought or opinion is a skill worth honing.
It’s hard because the beneficiaries of writing are different than the writers. It’s only in very strong cultures where execs put a premium on this on measuring talent. “Not only finish your work, and these three other tasks, but write about it too.”
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.
I work with a lot of people who didn't take the college track to become what they are today. I'm not saying that college is necessary or that one way is better or worse than the other, but the one thing I notice most about them is that they do not communicate through writing well.
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.
We can't have writing that effects clear communication, because nearly everyone is too busy, or too important, or has decided that pretending to be too busy is a way of increasing one's perceived importance, or all of the aforementioned. So they dash off sentence fragments, peppered with inflated vocabulary and buzzwords, and punctuated with ellipses, comma faults, and worse.
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.
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.
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'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 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.
Why is it so hard? Few are native speakers or passing for it. Few native speakers took their writing classes seriously, or at all. Almost no one reads for pleasure.
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'm often surprised by how bad people are able to handle basic computer stuff. For example: why TF don't you learn yourself how to type on a keyboard properly to accelerate your typing by like 10 times. Why TF are you not using the shortcuts your software is giving you to accelerate like 10 times.
It also results in newer iterations of products and software losing support for shortcuts and accelerators, because no one values or knows about them anymore, until every interface becomes dumbed down and considers touch as the primary and only possible way of interaction.
Related challenge: encouraging a culture of reading.
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.
Another related challenge: encouraging a culture of there being a predictable and searchable place documents live, so when someone has written a document you can actually find it.
We're experimenting with putting our documentation in our monorepo (written in markdown, compiled and published to GDrive, Confluence, if god-help-you you're searching on one of those platforms). Nitty-gritty api documentation lives in the service's protobuf file, but "evergreen" architecture overviews and technical designs live in the repo.
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).
I love keeping documentation in the same repo as the code, because you can enforce updates to the relevant documentation as part of the code review process. "This change is great - don't forget to update the docs in docs/blah.md before you land this pull request."
Ooh thank you, unittesting the documentation is a great tip that I will steal.
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...
I've adopted the doc of docs method and it has made my life incredibly easy! I was in a position where I'm a bottleneck of information because no one else in the company new about the product other than me. I wrote a ton of documentation for employees and users but I still was spending upwards of 20 hours every week just answering questions. I built the doc of docs in 2 hours and that has helped significantly. Combine this with always replying with a link instead of a dedicated explanation has been extremely fruitful!
An idea I had but never really executed on was a mechanism for tagging documentation as "should be reviewed at least once every X months" - for things like setting up developer environments.
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.
> 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.
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.
I have started making videos for people to watch (mostly me doing voiceover a screencast). It has had varying reactions, but I think it is becoming a valid medium.
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)
My main problem with videos and audio recording is they take so long to do. I made one for training at work and it's had high payback, but it's also around an hour of time per minute of content.
Look at pluralsight, everyone should be able to run video on 2x speed. One hour explanation I can watch in 30 minutes. If it would be written I could skim even faster and read interesting parts... But people don't read that is the problem.
That doesn't make it faster for ME to produce. And if people are running it at 2x then it's even less ROI.
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.
Video is good for brief pieces unless the whole point is to evoke emotion. Are you Spielberg? Are you going for Best Picture? Then keep your video very short. It isn't searchable, it moves at one speed regardless of how the audience is doing, and there's no way to copy text out of it so I can search for more information. It can't be cross-referenced, it can barely be indexed, and the text it contains can't be reformatted, unless I'm applying the formatting to subtitles which live in a separate file, in which case I'm really interacting with a text document after all, innit?
> 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.
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.
It's generally a good practice to start any request with "what did I do to find the answer/solve the problem?" That's both a check that you did your homework first and a way to avoid a bunch of back and forth narrowing down what the other party needs to give/tell you.
I believe that if you invest in a feedback mechanism for improving the signal:noise ratio of writing, people are smart and will naturally gravitate to where signal:noise is the highest. If people in an org aren't reading, I generally take it as a signal that documentation is incomplete and misleading, or the signal:noise ratio is way too low.
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.
> 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.
As an American, I've never heard of this, and can't even imagine it.
Once you become accustomed to this culture, it's difficult to go back. At one of my previous companies, there was a PowerPoint heavy culture. Every meeting had a presenter who brought PowerPoint slides. There's something to be said about PowerPoint being boring, but the bigger issue with PowerPoint culture is that the focus stays on the presenter and whatever information they provide... questions were typically saved towards the end. Some presenters who are open to disruption during their presentation will answer question, but it never fosters a rigorous, thorough deep dive.
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.
It's not like, 100% adopted at literally every single meeting, but it's pretty common across Amazon. Some orgs will do it more religiously than others, but no org will look at you funny if you request for a 5-10 min doc read before you start the rest of the meeting.
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.
As the other poster said, it's meant to be silent reading time.
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
Silent reading time in my experience. 5-10m of a 30m meeting, and up to 30m for longer design reviews or program docs. I personally love the format but I know some people get tired of writing so much.
> As much as possible, encourage people to post anything of interest to the public channels. Notice that I’m saying public channels, and not private messages, because we don’t ping anyone unless it’s necessary. We just want to make the information available.
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.
> 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.
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.
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.
Years ago I tried implementing a wiki at work as a knowledge base. While the user base remained reserved to select members of the team, everything was great. But the success of the wiki then became an invitation to the rest of the company. And soon knuckleheads were simply uploading Word documents to the wiki. So, instead of getting transparent, searchable content, we reverted to /index.html, circa 1992.
Something that was done at a previous company I was at was to dedicate a rarely used emoji reaction (IIRC, :eject:) to mean "this information should be captured somewhere other than slack. Messages that got that response would automatically be sent to a special channel, where they could be marked as complete. It worked okay.
A wiki is only as good as the big picture and structure of the people feeding it. Maybe you could use the logs of a chat to feed into a wiki. Just having everyone edit away with that ever is on their plate today, sure sounds like a wiki I don't want to use.
> A wiki is only as good as the big picture and structure of the people feeding it
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.
As someone who is extremely supportive of the concept of creating a culture of written communication I have to say I've had a pretty hard time understanding why people think slack or other similar chat-style communication even qualifies.
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.
> the company doesn't get that $100 bill right away, only if they can dig it out 2 years later.
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.
> 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.
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.)
You're assuming the new hire will be able to process all information and - if I'm reading your comment correctly - read all messages and / or e-mails sent to everyone. That's unlikely and unreasonable, nobody has the energy to trudge through all information when they join a new company.
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).
> You're assuming the new hire will be able to process all information and - if I'm reading your comment correctly - read all messages and / or e-mails sent to everyone.
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.)
Does posting it in a public channel really help solve that problem, though? With a powerful enough search method, maybe. But does Slack search qualify?
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.
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.
My company has been pushing for years the idea to limit the number of recipients to each email you send, simply because people spend so much time reading and managing email.
GitLab team member here. Written communication is vital in a remote company, and makes all types of companies operate more transparently and efficiently.
This is a great resource! I hope I can convince my team to implement something similar.
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?
In the software industry, these are several problems that prevent the success of written communication culture:
- 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.
> Some people have good writing skills, some have good technical skills. The ones who are good at both are rare.
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”
I would agree, I've worked with scientists and all types of engineers for decades and I think scientists used to rigorous lab work and coders tend to be better writers although it's not a super strong correlation.
I got the opposite experience. People with good technical skills often write dense, skip explaination of topics that they find easy to grasp, assuming the reader also find them easy (which usually is not the case).
I used to do this too - write dense essays and documentation that took forever to read. Then I took a class on business writing at my local university. It was well worth the time. It helped me focus on writing short, terse language that was simple and quick for the reader. If your organization does struggle with producing easy, well written communications I would highly encourage considering they enroll in some sort of 12-week long course with an experienced instructor who can provide direct feedback.
Eh - I find those people are often the same ones who write weirdly dense pythonic one-liners (cause less lines == good), don't write documentation for their code (cause all code they write == self-documenting), and assume that their interpretation of the English language is standard (even though it's often enough not their native language).
> Some people have good writing skills, some have good technical skills. The ones who are good at both are rare.
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.
I work in a team with some people who are dyslexic. I've noticed they don't communicate over written communication as much as some others, even preferring to create voice recordings or videos to share their thoughts. I definitely prefer written communication, but I think neurodiversity is one reason it's tough to make it a policy.
This is a very good point. There seem to be a non-trivial number of dyslexic engineers out there (I've worked with at least 3-4 over my career), and they struggle a lot to write - although they'll hide it out of cultural taboo. They tend to have excellent verbal communication skills though and seem to handle coding perfectly fine - one of them being one of the best engineers/mathematicians I've worked with. I wonder how we can better accommodate it, especially in a remote environment.
> I wonder how we can better accommodate it, especially in a remote environment.
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?
Be aware that going towards a document heavy culture doesn't make the smarmy types any less smarmy, it just changes how it is manifested.
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.
> You should try to have a single source of truth as much as possible. If you have many places where information can be found, it will affect both people writing the documentation and those trying to find it. The writers will have yet another blocker to just getting stuff written down. The readers won’t know where to look and will have to interrupt people in Slack, as opposed to referring to the knowledge base themselves.
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 what I did on my previous team to encourage writing and documenting while keeping the barrier low: use the internal/team blog feature in Confluence. I had a team of 5 so posting to that blog did not "spam" a lot of people, and you had to watch the "space" to get notifications at all.
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.)
A absolutely love the concept of internal blogging.
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.
A simple, dev-centric solution could be simply a Gatsby or Jekyll blog on a private repo. You can have your team members clone it & run on their own machine (easy but "hackish"), but I think it's actually possible to restrict access to team members on a published GitLab pages.
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?
Hm that sounds like a good solution. It's a bit more friction as I must ask people to make sure they follow a specific format (and don't forget to add it to the index page!!) rather than just clicking "new post" button and it doesn't have a "small team/space" feature like in Confluence, but it could work. These may seem like very small hurdles, but when you're asking people to do something they might not do on their own, every little bit of friction makes it less likely they'll actually do it, or more likely they'll be frustrated & resentful if you insist they do it.
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.
At my fully remote startup we operate a variation of this that I think can feel less onerous than a culture of verbose written communication.
- 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.
I'm building a product that combines screencasting with git, so you can talk about code as you work and discover it in your git history. I like how you describe it as "over the top," I think the biggest advantage is that video can be created while you code rather than writing which typically occurs after I'm done. The product is in beta and you can sign up here:
It integrates with code. The transcript on the right side is a combination of git diffs and audio transcription which is generated from your cast. Each git diff automatically commits to your git repository so you can reference the video from your git history.
Prior to quarantine, I had never heard of the concept of async communication. It felt like a fancy way of just saying "document more". Now that my whole department is WFH we've tried using Notion as our central repository of information. I don't think it lands every single feature described in the write up (e.g. search could be better), but, it has enough features to create write-ups and RFCs that are visually appealing to help get the point across.
We still hop on a quick Zoom 1:1 if we can't find the words to discuss over text.
To build on this -- for me async communications means not having to jump on so many meetings, and being able to organize/prioritize/delay stuff to respond to and batch them.
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.
Awesome piece, thanks for sharing. I agree that the key to effective communication is to lower the barrier to writing things down.
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.
I spent several years of my life reviewing corporate documents in an independent assurance role at a large company in the UK. The documents were a mix of bids and research reports intended for external use and internal docs associated with our sales/project process. I raised several concerns about our writing process to management and spent many long hours fixing docs at the last minute. But my concerns didn't get much traction with management.
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).
> As much as possible, encourage people to post anything of interest to the public channels. Notice that I’m saying public channels, and not private messages, because we don’t ping anyone unless it’s necessary. We just want to make the information available.
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?
> 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.
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.
> Based on these stories, you might be determined to demand high writing standards everywhere, right off the bat.
...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.
I've started working on a Q&A site that parses Slack logs and creates a thread on the site based on me asking people on Slack on how to do different things in our system. The problem with Wikis is friction. I'm hoping that reducing this to copy, paste and click OK will help.
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.
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.
Different people have different learning and communication styles.
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 think this article puts the cart before the horse. What's the point of good writing? Can you eat it? As argued at https://news.ycombinator.com/item?id=23147248 the goal ought to be effective remote collaboration.
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.
Written communication is a challenge for some people. Not everyone is as good of a writer and this skill does not map to coding skills. In the team I'm currently in, this is definitely a problem and I notice some people are not used to doing this and are effectively struggling to be part of the ongoing discussions.
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.
We’re having decent success recording and sharing small video presentations. People can speak in their own voice, they can point at things which is sometimes faster than describing them.
I’ve always been a stickler for clear writing, but recently I decided I will settle for effective communication of any form.
One of the main barriers to writing things down in organizations is the knowledge that anything written down can be subpoenaed. At least in the US, management of legal liability is a major part of running most organizations.
I've worked in places where everything is in email. That's become less common as email discoverability in court has become a thing. It wasn't some magical paradise.
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.
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.