14 ms·

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 as

• wonder_er 6y ago
  > 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 6y ago
    >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 6y ago
    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.
• WJW 6y ago
  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 6y ago
    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.
  • eru 6y ago
    > 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. Google has tech writers. Works well.
• mabbo 6y ago
  > 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_ 6y ago
    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. )
• AlexCoventry 6y ago
  > 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 6y ago
    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 6y ago
      Every couple of months or so, I guess.
• js8 6y ago
  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 6y ago
    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.
    • sib 6y ago
      >> I think it's also important to have a culture of reading, not just writing. That's certainly part of the key at Amazon. Documents are written to be _read_ and _used_ in critical decision-making. If you regularly don't read the documents distributed at the beginning of meetings and then ask questions that are clearly answered in those documents, you will be "profoundly unsuccessful" at Amazon. (How's that for a euphemism?)
• screye 6y ago
  > 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
• chrstphrhrt 6y ago
  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 6y ago
    > 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.
    • clairity 6y ago
      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."
    • vorpalhex 6y ago
• mathattack 6y ago
  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.
• hoorayimhelping 6y ago
  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.
• EvanAnderson 6y ago
  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.
  • jschwartzi 6y ago
    > I've seen some documentation come out of more scientific-oriented technical industries (think 'Theory of Operation' texts accompanying old lab instruments) that are just wonderful. I often use documentation as a gauge for how engaged a company is in making sure their product works in a way that makes sense. I've dropped part manufacturers before because they handed me documentation during evaluation that doesn't make any sense. Like the words are all on the page and someone obviously spent time writing the documentation but they don't make sense, like nobody actually read it. My bottom line there is that I'm not going to waste my time emailing you every time I need to solve a new problem with your product. I pride myself on being able to respond to questions about how our product works and I refuse to become the middleman between our end customer and your sales engineer. The first product I dropped for this was a thermal printer. After reading the documentation 3 times front to back I could not figure out what command to send the thing to make it issue a printout. I had to email the manufacturer for an explanation of the most important thing a printer can do.
• avip 6y ago
  Writing is half the issue. Most people are not very good readers, even of well-written material.
• janwillemb 6y ago
  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 6y ago
    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 6y ago
      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.
• munificent 6y ago
  > 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 6y ago
    > 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 6y ago
      It is a good term: https://en.wikipedia.org/wiki/Theory_of_mind 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.
• sl1ck731 6y ago
  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.
• closeparen 6y ago
  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.
• lukethomas 6y ago
  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/ 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.
• Juliate 6y ago
  Interesting take. Incidentally, the past 30 years have precisely seen the disappearance, but in very select types of businesses, of secretary/assistant/aide roles.
• mariodiana 6y ago
  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.