
Encouraging a culture of written communication - quintencls
https://www.mcls.io/blog/encouraging-a-culture-of-written-communication
======
nlawalker
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.

~~~
maxwelljoslyn
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.

~~~
randycupertino
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.

~~~
maxwelljoslyn
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.

------
blueyes
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.

~~~
munificent
_> Why is it hard?_

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.

~~~
clairity
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.

~~~
tra3
> 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.

~~~
BurningFrog
If you write code intending it to have good human readability - and you
_really_ should - you have the same problem writing code.

I spend a lot of time rereading my code imagining I'm someone else who's never
seen it before. Not sure everyone does.

------
simonw
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.

~~~
larrik
> 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.

~~~
strgcmc
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.

~~~
ryandrake
(Never worked for Amazon)

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.

~~~
strgcmc
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

------
Alex3917
> 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.

~~~
dragonwriter
> 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.

A team wiki is among the many better options.

~~~
Alex3917
> A team wiki is among the many better options.

Wikis are generally useless unless you have people whose job responsibilities
explicitly include creating content for them and keeping them up-to-date. In
my experience, if you have your PMs do this then each PM can cover 8 - 12
developers. Whereas if your PMs are just creating and pointing tickets but not
also spending a good percentage of their time on longterm documentation, they
can cover more like 12 - 16 developers.

Well maintained wikis are fantastic, but you almost never find them because
for even a mid-size startup that costs hundreds of thousands or millions of
dollars per year. That's the reason for public mailing lists and other email
archival products, because you're getting _most_ of the value a well-
maintained wiki but with mainly only the nominal cost of paying for the
software to keep it running.

I've thought a lot about this (obviously, given FWD:Everyone is in this
space), and figured out the actual reason why email is so much better than
Slack for knowledge retention; it's because with email you're forced to create
the metadata before having the discussion, and then the discussion keeps going
until people no longer have anything to say that matches the metadata --
subject, participants, visibility level, etc. (Discussions occasionally go off
the rails, but less than 5% of the time as long as the organization provides
some basic guidance on expectations for communication.) This metadata is key
though because not only does it help you find what you need to do your job,
but it helps you figure out what you don't need to read, which is perhaps even
more important.

Whereas with Slack you just start talking, and their software tries to figure
out what you were talking about after the fact. But despite having an AI team
working on this and having invested millions and millions of dollars into the
problem, their software doesn't really work at all, most likely because the
problem is basically impossible to do a good job of solving from a computer
science perspective.

edit: Obligatory self-promotional link:
[https://www.fwdeveryone.com](https://www.fwdeveryone.com)

~~~
mariodiana
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.

------
alohaandmahalo
GitLab team member here. Written communication is vital in a remote company,
and makes all types of companies operate more transparently and efficiently.

At GitLab, we don't just document to document. Instead, we recommend a
"handbook-first" approach, which we outline here in our public handbook:
[https://about.gitlab.com/company/culture/all-
remote/handbook...](https://about.gitlab.com/company/culture/all-
remote/handbook-first-documentation/)

We're also articulate about what we expect in terms of writing style
guidelines, part of our Communications handbook:
[https://about.gitlab.com/handbook/communication/#writing-
sty...](https://about.gitlab.com/handbook/communication/#writing-style-
guidelines)

~~~
MeetingsBrowser
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?

~~~
sytse
Not yet, I'm advocating that our issues for new features should read like the
eventual text in the release post.

------
letientai299
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.

~~~
gumby
> 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”

~~~
letientai299
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).

~~~
SamuelAdams
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.

------
raviisoccupied
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.

~~~
nvarsj
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.

~~~
SamuelAdams
> 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?

------
dpeck
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.

------
sqs
> 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 our handbook page that describes what has worked for us (at
Sourcegraph):
[https://about.sourcegraph.com/handbook/communication#sources...](https://about.sourcegraph.com/handbook/communication#sources-
of-truth). Only very specific Google Docs are sources of truth; all others are
just ephemeral scratchpads.

~~~
Koshkin
> _a single source of truth_

Naturally, these have been called "bibles": Unix Bible, Linux Bible, Linux
Command Line and Shell Scripting Bible, etc.

------
sequoia
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.)

~~~
Viliam1234
What are the blog features you actually need?

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?

~~~
sequoia
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.

------
bwaine
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.

~~~
tomatohs
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:

[https://paircast.io](https://paircast.io)

~~~
beckingz
That looks cool!

How does this compare to livecoding on a streaming platform?

~~~
tomatohs
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.

------
stlark
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.

~~~
wenc
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.

------
cborenstein
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.

------
KineticLensman
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).

------
MattGaiser
> 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?

------
marvinblum
> 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.

[1] [https://emvi.com/](https://emvi.com/)

[2] [https://emvi.com/blog/a-new-experimental-user-interface-
QMZg...](https://emvi.com/blog/a-new-experimental-user-interface-QMZgmZG1L5)

~~~
slx26
Hey, the cookie policy on your site appears in black text over a black
background on chrome.

~~~
marvinblum
Yeah that's broken at the moment. We'll fix it soon :)

------
AnonC
> 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.

------
dreen
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.

------
flukus
Mailing Lists.

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.

------
ChrisMarshallNY
I love this topic.

I like writing. I've been writing all my life.

In the last couple of years, I have taken to building a "personal brand," by
writing about the way that I design and develop software.

It's been really good for me. I find that it helps me to consolidate and focus
my thinking. It also helps me to feel accountable, and I'm a big believer in
accountability.

If I write something, it had _better_ be true and accurate.

I often review everything that I write in public, and make even small
grammatical corrections (I miss one, every now and then, though).

I also like reading. I _devour_ books; usually escapist fiction. The first
non-child book I ever read was _Where Eagles Dare_ , by Alistair MacLean. I
started reading because I lived in Africa, and the TV _sucked._

------
aantix
Writing is premature optimization.

YouTube is the most important asset on the web.

In fact, we’d be better off if most “thoughts” weren’t committed to virtual
paper.

In the beginning you want a medium that malleable, nuanced, high bandwidth.
Speech. Visual emotion. Voice inflection. How we’ve evolved.

It’s in those moments where ideas are challenged sbd change form quickly.

Then once they’re a bit more solidified, take a pass at writing. Which adds
further clarity.

I think eventually we find a place again for voice and video for remote work.
Something that isn’t a huge production but still async.

Yac or Loom look really promising in this area.

~~~
simonw
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.

------
rectang
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](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.

------
jillesvangurp
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.

------
DenisM
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.

------
bryanmgreen
Written communication is simply an extension of overall communication.

If communication is only encouraged as a tool to transfer the needs of an
executive to teams and then individual contributors, it will wither and die.

To improve written communication, you must improve the culture first.

------
Avicebron
Encouraging a culture of people who now have to work in a cover their ass
territory...welcome

------
frank2
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.

~~~
MattGaiser
How much of what is written day to day by software developers would be legally
interesting?

------
Spooky23
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.

------
lazyant
I'd add: keep a simple text or markdown file with daily notes.

------
sub7
As a developer, nothing sounds worse than a bunch of people typefarting and
expecting everyone else to read their stupid thoughts.

If you want to type, please do it in an IDE.

------
m1117
It has a huge downside. It can be boring and too corporate.

