[HN Gopher] Encouraging a culture of written communication
___________________________________________________________________
Encouraging a culture of written communication
Author : quintencls
Score : 369 points
Date : 2020-05-11 12:29 UTC (10 hours ago)
(HTM) web link (www.mcls.io)
(TXT) w3m dump (www.mcls.io)
| letientai299 wrote:
| 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.
| MeetingsBrowser wrote:
| > 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.
| gumby wrote:
| > 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 wrote:
| 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).
| bradlys wrote:
| 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).
| SamuelAdams wrote:
| 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.
| zwieback wrote:
| 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.
| sub7 wrote:
| 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.
| [deleted]
| m1117 wrote:
| It has a huge downside. It can be boring and too corporate.
| nlawalker wrote:
| 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.
| karatestomp wrote:
| > 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).
| thu2111 wrote:
| 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.
| karatestomp wrote:
| > 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.
| klenwell wrote:
| I love this topic, too. And this is so true:
|
| > 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.
| toast0 wrote:
| 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.
| dcminter wrote:
| > 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.
| L_Rahman wrote:
| 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.
| wnevets wrote:
| >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.
| aspaceman wrote:
| 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.
| mandelbrotwurst wrote:
| > If after "resolving" something you can't actually write
| down what was accomplished, nothing was resolved.
|
| It's possible to "resolve" something / determine what to do
| next without writing anything down.
|
| Often the ideal outcome is simply an agreement that Person
| X will move forward with approach Y.
| cmwelsh wrote:
| 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.
| wnevets wrote:
| >Often the ideal outcome is simply an agreement that
| Person X will move forward with approach Y.
|
| Which you can write down if you so desire.
| mandelbrotwurst wrote:
| 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!
| hadsed wrote:
| 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.
| gregmac wrote:
| > 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.
| [deleted]
| philwelch wrote:
| > 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.
| maxwelljoslyn wrote:
| 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.
| aspaceman wrote:
| 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.
| kahmeal wrote:
| 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.
| d23 wrote:
| 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.
| MattGaiser wrote:
| > 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?
| Alex3917 wrote:
| > 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 wrote:
| > 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.
| seqastian wrote:
| 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.
| dragonwriter wrote:
| > 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.
| zozbot234 wrote:
| A private Q&A facility might be a useful middle ground.
| Then use the most frequently referenced topics in the Q&A
| as a guide to structuring a wiki.
| dllthomas wrote:
| 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.
| Alex3917 wrote:
| > 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
| mariodiana wrote:
| 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.
| eitland wrote:
| > it's like taking a $100 bill and lighting it on fire.
|
| Interesting example, appreciated!
|
| Let me try to improve it:
|
| _it 's like taking an envelope that might or might not contain
| an $100 bill and lighting it on fire._
|
| Not everything is useful, but we don't know until later.
|
| Also, the company doesn't get that $100 bill right away, only
| if they can dig it out 2 years later.
|
| Still, good example.
| Alex3917 wrote:
| > 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.
| eitland wrote:
| > 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.)
| benhurmarcel wrote:
| 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.
| smaddox wrote:
| 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?
| noisem4ker wrote:
| I've found Slack search to be impressive in a multi-thousand
| people workspace. Results came up very fast and well
| summarized.
| munchbunny wrote:
| From experience, no.
|
| The problem with team chat is that it has very low signal to
| noise ratio, which makes it hard to find structured info.
| CPLX wrote:
| 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.
| MattGaiser wrote:
| Wouldn't that still need curating to be useful?
|
| 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.
| mattbk1 wrote:
| Posting public questions can be a very fast way to find the
| "someone else" to ask, in my experience.
| munchbunny wrote:
| _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.
| Cthulhu_ wrote:
| 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).
| Alex3917 wrote:
| > 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.)
| alohaandmahalo wrote:
| 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...
|
| 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...
| MeetingsBrowser wrote:
| 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 wrote:
| Not yet, I'm advocating that our issues for new features
| should read like the eventual text in the release post.
| benhurmarcel wrote:
| Great resources, thank you. This is remarkable that this is
| public.
| lazyant wrote:
| I'd add: keep a simple text or markdown file with daily notes.
| cborenstein wrote:
| 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.
| rectang wrote:
| 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.
| simonw wrote:
| 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.
| lifeisstillgood wrote:
| 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)
| grogenaut wrote:
| 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.
| blattimwind wrote:
| They take a long time to produce and to consume as well.
| Video is a neat but inefficient form of communication for a
| lot of content.
| msla wrote:
| 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?
| ozim wrote:
| 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.
| JoshuaDavid wrote:
| 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.
| gen220 wrote:
| 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).
| simonw wrote:
| 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."
|
| You can even write unit tests that verify that certain
| things are mentioned in the documentation:
| https://simonwillison.net/2018/Jul/28/documentation-unit-
| tes...
| gen220 wrote:
| 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".
| andreareina wrote:
| Are you copy/pasting the md input into Confluence, the
| formatted html output, or doing something else?
| gen220 wrote:
| We use pants as our build tool, and somebody has
| graciously contributed a plugin for pants that generates
| confluence pages: https://github.com/pantsbuild/pants/blo
| b/master/contrib/conf....
|
| 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.
| specialist wrote:
| FWIW, my last team had too much documentation. It's just so
| hard to cull stale info. I really struggled to discern what I
| could ignore.
|
| Everything needs a default automatic TTL, just like renewable
| leases.
| larrik wrote:
| I'll put it in Confluence!
|
| _can never find it again..._
| simonw wrote:
| Two approaches I've used for that:
|
| 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...
| specialist wrote:
| Maybe also add basic metrics. Like number of views,
| popularity over time, sparklines for edit activity, ...
|
| Maybe even some social features, with a decay rate. So
| teammates recently tagging things as "helpful!" could nudge
| me to pay attention.
|
| Any additional signal to help noobs like me while foraging.
| SamuelAdams wrote:
| At that rate you're better off buying some software that
| handles all this for you. Enter Microsoft Sharepoint.
| Yikes.
| simonw wrote:
| 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.
| larrik wrote:
| > 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 wrote:
| 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 wrote:
| (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 wrote:
| 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
| kevan wrote:
| 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.
| [deleted]
| simonw wrote:
| Search for 'Six-Page Narratives' on this shareholder letter
| from Bezos for a bit more detail: https://www.sec.gov/Archive
| s/edgar/data/1018724/000119312518...
| larrik wrote:
| Nice, thanks
| tracer4201 wrote:
| 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.
| pm90 wrote:
| > 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.
| Alex3917 wrote:
| > 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.
| SilasX wrote:
| 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.
| gen220 wrote:
| 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.
| sqs wrote:
| > 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....
| Only very specific Google Docs are sources of truth; all others
| are just ephemeral scratchpads.
| Koshkin wrote:
| > _a single source of truth_
|
| Naturally, these have been called "bibles": Unix Bible, Linux
| Bible, Linux Command Line and Shell Scripting Bible, etc.
| frank2 wrote:
| 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 wrote:
| How much of what is written day to day by software developers
| would be legally interesting?
| blueyes wrote:
| 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.
| wonder_er wrote:
| > 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.
|
| edit: grammar x2 It's not easy to write clearly.
| ghaff wrote:
| >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.
| moneil971 wrote:
| 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.
| janwillemb wrote:
| 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.
| kebman wrote:
| I don't worry too much about it. In fact it kinda makes me
| happy. It just means your job is now safer, since you DO know
| all those shortcuts. ^^
| noisem4ker wrote:
| 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.
| EvanAnderson wrote:
| _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.
| AlexCoventry wrote:
| > Writing is hard. Why is it hard?
|
| Usually because the underlying ideas are inchoate, so bad
| writing is often a good diagnostic for muddy thinking.
| gonzo41 wrote:
| 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.
| AlexCoventry wrote:
| Every couple of months or so, I guess.
| lukethomas wrote:
| 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.
| munificent wrote:
| _> 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.
| BurningFrog wrote:
| > _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_
|
| So very true.
|
| "Theory of mind" is a good term. "Empathy" is another.
| munificent wrote:
| It is a good term:
|
| https://en.wikipedia.org/wiki/Theory_of_mind
|
| My wife and daughter are on the spectrum and it has been an
| interesting (and often difficult) experience to spend a lot
| of time around people whose intuitive theory of mind isn't
| as strong as a typical person's.
|
| It made me realize how much we take for granted the
| dedicated brain regions we have for social cognition. For
| most of us, it's completely effortless to know "Oh, I told
| her ___ so she'll want ___." We do that processing as
| automatically as we recognize faces or climb stairs with a
| cup of coffee in our hands.
|
| But for people on the spectrum, it's like the wetware is
| reduced, like having bad balance or no sense of direction.
| They can do the same task _deliberately_ by focusing all of
| their attention on it, using the general-purpose calculator
| part of their brain to do a job most of us rely on
| dedicated hardware for.
|
| Doing that takes a _lot_ out of them. Imagine if every
| conversation felt like a calculus test. When they don 't do
| that, it manifests itself in all sorts of behaviorally
| strange ways. There's the classic stuff like unusual affect
| and eye contact. But the one I notice a lot now that I'm
| attuned to it is pronouns. They will often use a pronoun to
| refer to a noun they've never introduced, because _they_
| are already thinking of that noun and didn 't notice that
| they never mentioned it explicitly.
|
| Brains are weird.
| clairity wrote:
| 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 wrote:
| > 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.
| clairity wrote:
| 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.
| BurningFrog wrote:
| 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.
| munificent wrote:
| _> 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.
| Juliate wrote:
| Interesting take.
|
| Incidentally, the past 30 years have precisely seen the
| disappearance, but in very select types of businesses, of
| secretary/assistant/aide roles.
| hoorayimhelping wrote:
| 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.
| WJW wrote:
| 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.
| Viliam1234 wrote:
| 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.
| js8 wrote:
| 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.
| TeMPOraL wrote:
| 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.
| mariodiana wrote:
| 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.
|
| Writing isn't difficult. People are difficult.
| mabbo wrote:
| > 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.
|
| It's an investment that pays off.
| andrei_says_ wrote:
| 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. )
| screye wrote:
| > Writing is hard. Why is it hard ?
|
| 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
| sl1ck731 wrote:
| 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.
| avip wrote:
| Writing is half the issue. Most people are not very good
| readers, even of well-written material.
| chrstphrhrt wrote:
| 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.
| ativzzz wrote:
| > 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.
| vorpalhex wrote:
| > 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.
| clairity wrote:
| 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."
| thu2111 wrote:
| 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.
| mathattack wrote:
| 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.
| closeparen wrote:
| 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.
| DenisM wrote:
| 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.
| aantix wrote:
| 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 wrote:
| 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.
| [deleted]
| raviisoccupied wrote:
| 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 wrote:
| 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 wrote:
| > 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?
| marvinblum wrote:
| > 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/
|
| [2] https://emvi.com/blog/a-new-experimental-user-interface-
| QMZg...
| slx26 wrote:
| Hey, the cookie policy on your site appears in black text over
| a black background on chrome.
| sequoia wrote:
| 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.)
| emilecantin wrote:
| 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.
| Viliam1234 wrote:
| 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 wrote:
| 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.
| simonw wrote:
| 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.
| jillesvangurp wrote:
| 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.
| bwaine wrote:
| 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 wrote:
| 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
| beckingz wrote:
| That looks cool!
|
| How does this compare to livecoding on a streaming platform?
| tomatohs wrote:
| 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.
| AnonC wrote:
| > 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.
| stlark wrote:
| 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 wrote:
| 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.
| KineticLensman wrote:
| 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).
| dreen wrote:
| 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.
| dpeck wrote:
| 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.
| bryanmgreen wrote:
| 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.
| Spooky23 wrote:
| 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.
| Avicebron wrote:
| Encouraging a culture of people who now have to work in a cover
| their ass territory...welcome
| [deleted]
___________________________________________________________________
(page generated 2020-05-11 23:00 UTC)