Writing well is an undervalued skill in life, not just in engineering. When you work on a team of peers with similar skills in your field, whether that field is engineering or something else, being able to write well and communicate well become strong differentiators. FWIW, I'm pretty sure that writing (reasonably) well online is what got me a job in venture capital after ten years as an engineer.
David Perell (host of the North Star Podcast) has been tweeting a lot of good things about the value of writing + writing tips:
I disagree that writing is undervalued. I think that writing is highly valuable and highly rewarded...but that the path to overcome challenges with writing is bafflingly mysterious. Does anyone know of a therapist who has experience helping people overcome writing anxiety?
I genuinely don’t know how to find one. Therapist-shopping is baffling.
I ask this as a software engineer who can produce pretty solid writing if given enough time but for whom doing so prompts thoughts of severe self harm. I was pushed to resign from my last job as a result of handing in a nearly-blank self-evaluation during my company’s performance review process, so I’m willing to spend... I guess up to $8k, (maybe more? Anything’s better than suicide to be honest. I love life in general and suppose it would be rational to spend half my income to eliminate the risk of it) On getting this finally solved after 2 decades of occasional agony.
I used to help coach college friends in their writing. Often their first drafts would have complicated pretentious sentences that really weren't even parseable as sentences, and first I'd ask them, "What do you mean here?" And then when they'd explain, "Write that down!" Perhaps something like that would work for you, to help take you from a "composing" mindset to a "conversing" mindset. You could even record yourself or use some dictation software. It may even make your writing easier to read.
It might also reassure you that professional writers often say, "There is no writing, only re-writing." The first draft is never the final draft, so you don't have to take it seriously. Just jot down whatever comes into your head. Some people start with an outline, scattered words with arrows connecting them, questions to answer, blank spots, etc., whatever helps to keep you moving forward. Getting started is the hardest part. Keats used to chain himself to his desk to force himself to write something. Sometimes it even helps to set yourself a silly challenge, like randomly open the dictionary ten times to pick ten words you have to include. They don't have to make it into the final draft---but they could. :-)
You might also want to read some books about good writing. Strunk & White is good. Their advice is "keep it simple." Clear and Simple as the Truth is sort of a step past that to a slightly more artful style. Another book I enjoyed was The Artist's Way, which despite the title has a lot about writing.
I don't know anything about professional therapy, and perhaps these suggestions are all way off the mark for you, but I offer them just in case you find them useful. I'm sorry that writing is so painful for you!
> I used to help coach college friends in their writing. Often their first drafts would have complicated pretentious sentences that really weren't even parseable as sentences, and first I'd ask them, "What do you mean here?" And then when they'd explain, "Write that down!" Perhaps something like that would work for you, to help take you from a "composing" mindset to a "conversing" mindset. You could even record yourself or use some dictation software. It may even make your writing easier to read.
Interesting. I often encounter the problem at other the end of the spectrum: People who are used to verbal communication, which often results in rather scarce writing that resembles snippets of a verbal conversation rather than a cohesive thought and therefore lacks to details to properly understand meaning and intention.
Usually that kind of writing requires a lengthy series of follow up questions to learn anything meaningful about the original idea of the author. Conciseness is onyl valuable if it doesn't sacrifice substance and meaningful content.
I don't have that strong of a reaction, but realized fairly recently that I also get a lot of anxiety from writing on demand.
What works for me is not starting from scratch. If I do, I'll either never get it done or procrastinate until the last minute (while building up an incredible amount of anxiety in the interim).
Instead, I try one of two things:
1) Repurpose something else I have. As long as I have a seed to build off of or skeleton to frame against, I'm able to tackle it fine. If I have no frame of reference, I'll try to find one. In your self-evaluation case, I'd ask for an anonymous example from your boss or HR to understand the expectations.
Or, 2) Ask a trusted friend or colleague to check it over. My work context switches from C-level client management to architecture and analytics-related dev work. While I can articulate a matter to any audience, that also means I can completely miss the mark if I misjudge an audience/recipient I haven't addressed before. So I'll brain dump a bunch of stuff, then ask someone who's closer to the target audience or more familiar with them. They'll help act as a sanity check whether I'm on the right page, and I use their feedback to refine things.
I'm not sure if either of those coping strategies will help for you, but I wanted to mention them just in case!
I think the "starting from a frame of reference" is good, I wouldn't necessarily ask HR for what they expect. That's pushing them to commit to something, which they don't want to do either. Instead, look online.
Self-evaluation is just another piece of bullshit process where people's expectations are formed around the bullshit everyone is handing in. Chances are that what these people are handing in is highly informed by whatever the top Google results are.
Ordinary people don't necessarily have qualms about working this way, people with anxiety issues often have this misguided desire to be "original". Being unoriginal is fine though, it hooks into familiarity and it doesn't cause extra work. Nobody is excited about reading the performance reviews, it's just something to get done.
I think any therapist who specializes in anxiety would be a good fit. Some studies show CBT (cognitive behavioral therapy) to be as effective as medicine.
www.psychologytoday.com has a search for finding local therapists. I'd start there.
And good luck! Feel free to reach out if you have any other questions.
I'm a naturally bad writer but somehow I managed to become confident in writing documentation, cover letters etc. For cover letters asking friends/family for feedback had helped me a lot, also for this specific topic there are a bizillion great books about the topic - amazon is your friend. Or google: how to write performance review
That said, I think depending on the kind of writing you want to do, there is probably a book/article about it.
Also what is a nice strategy that always works for me: start with brainstorming or random bullet points. Put things in order, like a 1 or 2 level hierarchy. Mark important things, throw out things you are not comfortable with. Add some details.
Then get an example text. In the case of cover letters there's always a standard structure: intro, main part, end. And then replace it with your words. Also in the case of reviews, maybe you can ask your colleagues to see how they structure their writing and even review yours before you hand it in.
Are you terrible at writing in general, or specifically for self-evaluation?
Personally I feel very confident at writing, to the point where I fantasize about a professional writing career. But I can completely imagine freezing up at a self evaluation.
Have you considered that you might have ADHD or some other cause for your writing difficulties besides just anxiety? If so, it may help to work with an occupational therapist to come up with specific strategies to work better (e.g., setting up an environment conducive to writing, scheduling time to write, outlining before beginning).
In what sense is it under-valued? There is a fabulously popular musical about how the ability to write well can propel you to the heights of leadership of a nation. In my experience, people believe that the ability to write well is key to professional success.
Where are the people who believe that writing is not a valuable skill?
I agree that when people talk about writing, it seems like they value it. But in practice I believe it's undervalued. I essentially don't know anyone that, given the choice of leveling up their writing skills vs their job-specific skills, actually focused on writing.
You have to write at least a few coherent, error-free paragraphs in your resume typically. It's something of a good filter to toss out people that either can't, or can't be bothered to, write clearly for that small sample.
People generally don't read prose in technical resumes, moreover, I'd never hold it against a candidate because they're nudged into writing in a highly summarized, notation style. Unless there were blatant issues with language, and then I'd be super concerned about blowing off an 'english as a second language candidate'. About 1/2 of devs it seems are from 'somewhere else' and we can't expect them to have world class technical chops and perfect fluency.
In my experience developers tend to underemphasize improving their writing or communication skills (related but separate skills) as a part of their professional development. I seldom see managers suggest and send their reports to workshops or classes for professional writing. I have seen it, but only twice ever, and only an executive doing it for an upper level manager.
In reality, I think this should be an almost universal type of job training for developers.
I feel like we let new engineers down by not guiding them toward resources where they can improve their social/writing skills.
Where is the brilliant.org for social/emotional/communication skills?
Social skills are presented as an obvious thing and the lack thereof is grounds for ridicule and derision rather than pointers to resources. (Note: How to win Friends and Influence people is a good base, but the Harvard Negotiation Project has many more good books. Also, Charisma on Command is a great youtube resource)
We have them be taught writing by literature majors who insist there’s some meaning to blue curtains but can’t be bothered to explain why or what the principles behind making that judgement are. (Note: a great explanation of how symbolism works can be found by putting “extra credits symbolism” into google)
I think it's important to separate the skills out. Communication, social, and writing skills are three different things, and it's quite possible to learn all three without a literature class. You can thank the middle school and high school curricula for the unfortunate association.
Once you're in college, you can get the writing without the symbolism by taking writing classes, especially creative writing ones. But I amost never saw engineers do it, often out of a "what am I going to do with it? Write short stories for my documentation?" reaction. Their loss.
After college, there are plenty of books and classes you can take, but like programming it often comes down to practicing and getting feedback. There are websites and your local area likely has writer circles. You can get into short story writing and you'll get good feedback from others. Unlike programming, writing is an inherently social activity. In order for your writing to work, it must pass through the lens of another human.
Anecdotal evidence: in large corporations good luck finding leaders who can write anything in a clear and concise way. There are some, but by far and large they are exceptions. So much for "write well can propel you to the heights of leadership of a nation", playing politics is definitely the more important predictor than anything else.
FWIW, "Writing Without Bullshit" by Josh Bernoff (Harper Business, 2016) tackles this truth head-on. I liked what I saw when I took a look at my local bookstore and it's gotten excellent user reviews on AMZN.
It'd make a great gift for the PHB manager/director/CEO in your life <smirk>.
Maybe undervalued is the wrong word, as clearly the economy rewards people who can write well. It’s just that it often seems overlooked. Job ads and CVs sometimes vaguely mention ‘good communication skills’, but I rarely see any specific mention of writing.
me too. writing concisely has helped me throughout my career, but that wasn't always the case. i undervalued writing growing up and slowly fell behind my peers. that finally caught up to me in college where i struggled to distill and express the often conflicting ideas squirming around in my head.
but a love of novel ideas led me to take extra liberal arts courses, accept the resultant mediocre grades, and ultimately improve my writing. becoming a teaching assistant for an engineering writing class was where, in comparison with my younger peers, i could finally see that i'd indeed improved (and hopeful that the poor writing i graded wasn't indicative of future skill!).
I'm curious about your experience. How do you think your writing translated into value in the eyes of the VC world? Or was it that you'd built a platform online first through your writing and then they solicited you?
In my experience my ability here has always been valued after the fact; I have the strong impression that few companies value writing, even as a secondary skill, or see it as a differentiator.
A few positive experiences I've had related to writing:
1) I used to write a lot on Quora. Being an engineer who can write made my future VC partners believe that I could do more than engineering. I'm pretty sure that building a decent readership base on Quora is what put me on my partners' radar in the first place.
2) Writing on my blog/Twitter/etc has helped put my name and my fund's name on more people's radars and generated a lot of leads for potential investments. As an introvert, writing has been an excellent solution to not wanting to go to networking events/dinners/etc. :)
On the startup side, writing/content marketing are great ways to get customers, especially for b2b companies. Having a strong product matters, but being able to articulate the product's value and your company's expertise through writing is incredibly helpful.
One doesn't always get to meet people, sometimes and tbh quite often it has to be on LinkedIn,via email or even a letter.. Ability to do it well sets you apart and also brings confidence to those you try to communicate with.A well written proposal to a VC is 100 times better than some mish mash of words.
I agree with the author that writing is one of the most undervalued skills for SWEs, but for a completely different reason - it forces you to reason things through properly, even if nobody else will ever read what you write.
Writing a couple of pages of design docs or an Amazon-style 6 pager or whatever might take a few days of work, but can save weeks or more of wasted implementation time when you realise your system design was flawed or it doesn't address any real user needs.
I'm currently trying to get some folks on the same page regarding the most basic of things in a design document, and the passive resistance is just astonishing to me.
Just adding the following text seems to upset some people:
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
It's like they don't want to be pinned down to an exact meaning in design documents! And don't even think about trying to "force" people to use a style guide like RFC 7322, or even an authoritative list of initialisms, acronyms, and abbreviations.
Is it too much to ask to have people use the same term to refer to a project, environment, component, etc? It saves so much time when you don't have to spend effort tracking down what someone means when they say "stage is broken".
This has already gotten too rant-y but it burns my butt so much! So much wasted effort!
It's the key to 'effective communication' in particular environments.
Words have meaning, and because language is vague, we help it a little by pinning down the meaning of certain words: this is for clarity, it's not a constraint.
>I don’t think the key to effective writing is following a bunch of standards.
Well it is if you're being judged on compliance to the standard. Have you never worked in government? But hey if you don't like the standard then just make your own: the great thing about standards is there are so many to choose from!
It depends on what you are writing. Also, there is a question of readability. A document written in legalese is certainly “accurate,” but that doesn’t make it comprehensible. Writing with clarity isn’t about following a standard, it’s about using language in such a way that the consumer of that language understands the message. If documents were written following like the RFC, they’d be incredibly tedious to read. English isn’t a computer language, there is a such thing as context, tone, and diction. Of course if you are actually writing a legal document or standards document, certainly use that idiom.
That's a pretty asinine response to a point that is substantially correct. Insisting upon a set of rules for otherwise commonly understood words (an RFC defining "MUST") is usually a pedantic waste of time, and will actually reduce the quality of the finished product. No one is here to dispute the usefulness of approximately correct contemporary grammar. I would dispute the usefulness of insisting that design docs conform to APA style requirements or some other nonsense, unless there were very clear reasons for insisting on that level of uniformity (documentation for a pacemaker, for example).
> Insisting upon a set of rules for otherwise commonly understood words (an RFC defining "MUST") is usually a pedantic waste of time
I would agree, except the field of programming seems to have a very large number of pedants. Unfortunately, earlier in my career I was in the room many times where the lead or programmers told the PM or stakeholder "well it didn't say that exactly."
>I would agree, except the field of programming seems to have a very large number of pedants.
It's been a few years but at least when I worked as a NASA subcontractor those standards were (IMHO) to both ensure compliance to process and frankly spread around the blame if something failed despite compliance. Since none of us are writing code to fly on the Space Shuttle I'll agree with you most of the time pedantry for the sake of it is a waste of time. Still, if someone wants to be a pedant about writing code for an automated teller machine or a voting machine then I'd say it's time well spent.
You are assuming that everyone working with the document is a native English speaker and / or has worked to a standards based development system.
Even so back in the day ICL managed to ignore a counter MUST start from Zero in implementing an X.400 stack - and you wonder why the uk No longer has a mainframe supplier.
I'm not a native English speaker. Half of the team I manage are native English speakers,the rest are not. The recent project they did on communication templates was checked by the French colleague,while I no longer forward some of the files to English native speakers because they can't form sentences thst are clear enough to understand by others. It is not easy for a lot of people.
I work with a team that spans native speaker to barely able to form English sentences, and communicating clearly in a mixed audience like that is really a completely separate skill from native language use.
For the ones with minimal English it's often clearer to use phrasing that a native speaker would say is obviously wrong, but matches their native language patterns. Or use simpler but not-quite-appropriate words.
And for the native speakers, the awareness (or self-regulation) to eliminate idioms and less common vocabulary is nigh-impossible for some people.
I find that awareness and avoidance of idioms is much easier once one has learned (well) a second language. I am fluent in Esperanto, and somewhat subconsciously translate much of what I write as I am writing it. It leads me to choose simpler words and grammatical constructs, and to avoid circumlocutions and especially idioms.
That's… not the point of RFC 2119. The point is to specify specific words used to indicate various levels of adherence to a standard. Maybe "must" clearly indicates a strong requirement to you (as opposed to an optional requirement). Does "should"? How about "shall"? The English interpretation of these words contains shades of grey, and different people will interpret them differently, sometimes even depending on context.
Why invite such ambiguity? It leads to problems, when the designer writes "shall" and the implementer takes it as a suggestion, or the designer writes "should" and the implementer sinks months trying to satisfy what turns out to be a requirement the implementer intended as optional in light of unknowns.
Clarifying terms eases communication. RFC 2119 isn't about defining basic words of the English language for imbeciles. It's about selecting words to indicate precise levels of compliance. They could have equally named the levels P0, P1, and P2. Instead they chose MUST, SHOULD, and MAY to indicate the same, while reading more easily as part of a sentence.
This argument doesn't make any sense, because someone who somehow manages to find 'must' ambiguous would also find 'absolute requirement' ambiguous. The RFC doesn't solve the problem, if there is a problem in the first place.
If 'absolute requirement' is clear enough as plain English in a normal sentence, without having to capitalise it, then why isn't 'must' clear enough?
You must not see the value in dictionaries, or explanatory text, or examples at all.
Let me rephrase: would you have a problem with RFC 2119 if it defined the terms P0, P1, and P2? If so, why? (That would be a bizarre stance to me.) If not, why do you see it as problematic that they chose the words MUST, SHOULD, and MAY, instead of P0, P1, and P2? After all, there's no logical fault in choosing more memorable names.
I see this problem in code often too. Some people think it's sufficient to give functions and variables English names with "obvious" meanings. Yet however "obvious" the meaning is to you, it can be interpreted differently by different people because English is ambiguous. Such symbol names without comments ascribing them a meaning plain English might as well just be "xyzzy", "qwert", and "l33t". English-named symbols are mnemonic devices, nothing more.
Example: the code base I work on as two commonly-used functions, "findObject" and "getObject". One returns a reference to an object only if already cached; the other fetches it from disk if necessary. Which does which? Does "find" mean to go out and actively "find" the object? Or is it referring to the fact that it only returns the object if it is "found" in cache? After all "get" is a pretty active verb. I guarantee you, whoever named these (and didn't document them!) thought like you, that the meanings were "obvious" and "unambiguous". And I bet they were, to that person, at that time, in that context.
I for one, can never remember whether SHALL is mandatory or not, or whether SHOULD indicates nice-to-have-but-not-mandatory, or purely optional. They're terrible English words to use in a formal specification. But the mere fact that RFC 2119 disambiguates them as formal terms in the context of specifications makes them eminently usable for that purpose.
These words already have definitions. You can look them up in a dictionary. Or almost all speakers know them anyway.
Why do we need an RFC, and to write them in capital letters?
What does the RFC add to anything? If you removed the capitalisation and the reference to the RFC then your text means exactly the same thing, as the words already had the same meanings.
> English is ambiguous
Well then how does the RFC solve that problem? Their definitions of these terms are using other English words which are also ambiguous.
> I for one, can never remember whether SHALL is mandatory or not
What do you think 'shall' means in a normal conversation? How could it mean anything except mandatory? In what normal English context does 'shall' mean optional?
If a normal person tells you that you must submit your expenses before the end of the month do you get confused about whether it's required or not? If they write it in capitals and refer you to the RFC do you suddenly understand now?
> Well then how does the RFC solve that problem? Their definitions of these terms are using other English words which are also ambiguous.
The same way that a dictionary definition clarifies the meaning of a single English word. By using complete sentences to rule out grey areas.
I see no point in furthering this discussion. Your defeatist assertions like the above "there's no possible way to disambiguate English", your refusal to admit that apparent synonyms such as "must" and "shall" might not be perfect synonyms to people other than yourself, and your repeated sarcasm and snark, suggest to me that you do not see the opposite viewpoint as legitimate, and therefore are not amenable to changing your viewpoint.
> The same way that a dictionary definition clarifies the meaning of a single English word.
Right, so use the dictionary we already have! Why do we need the RFC?
> "there's no possible way to disambiguate English"
This quote isn't from me. I didn't say that - I don't know where you've got it from.
> your repeated sarcasm and snark
Sarcasm and snark? I don't use those rhetorical devices if I can avoid it. I don't think I've used them in this thread at all! I don't know where you've got the idea that I'm not arguing seriously from. I'm sorry I gave that impression.
My legitimate argument is that nobody is honestly confused by words like must - nobody. The RFC is over-the-top formalism where it's not needed.
The RFC is far more useful in dealing with the word "should". It is used in the standards to mean something that is optional but strongly recommended ("there may exist valid reasons in particular circumstances to ignore a particular item"), whereas in english the first definition that comes up is "used to indicate obligation, duty, or correctness".
To me it seems that there could easily be confusion between these two interpretations.
> RFC 2119 defines a standard set of key words for describing requirements of a specification. Many IETF documents have found that these words cannot accurately capture the nuanced requirements of their specification. This document defines additional key words that can be used to address alternative requirements scenarios. Authors who follow these guidelines should incorporate this phrase near the beginning of their document:
> The key words "MUST (BUT WE KNOW YOU WON'T)", "SHOULD CONSIDER", "REALLY SHOULD NOT", "OUGHT TO", "WOULD PROBABLY", "MAY WISH TO", "COULD", "POSSIBLE", and "MIGHT" in this document are to be interpreted as described in RFC 6919.
(Spoiler: this is an April 1st RFC. That said, I have wanted to use or used "OUGHT TO" so many times…)
Without knowing why you want the RFC 2119 language adopted within your organization, I can say that although it's very important that everyone use the same words to refer to the same things, I would be careful when applying rigorous definitions to those keywords.
Are you writing standards for networking, where there could be multiple implementers and you want to be clear to everyone what their implementation has to do? What value do the definitions add? Do people ask questions or have disagreements without the rigorous definitions?
When you say "must" with the weight of RFC 2119, you need to consider the "or what?". If you're writing a standard, what force does it carry? Is there a certification? Is it a marketing issue? Will other implementations put the bad implementation on a blocklist? Will they actually fail to interoperate in practice? Or can someone get away with violating the "must"?
For in-house design documents: or you're not a team player. You've done a bad job. This will screw up something, somewhere, at some point, costing people time and money.
Show them civil engineering codes, specs, and plans. It’s nothing but those words.
You can pull up ASCE standards, the IBC OR CBC, Caltrans Highway Design Manual or Specs, Greenbook, Any city design manual, etc. etc.
They’ll get the idea.
Is it really wise for design documents to rely on nuances of language? How many of your readers could you reasonably assume have read RFC 2119? How many of your readers could you reasonably assume to be native English speakers? How many native English speakers would be able to comfortably articulate the difference between "shall" and "should"?
And no, not every design document is intended for professionally-licensed engineers, safety-critical applications, or to be used in legal courts. Even when safety is not at stake, writing remains important.
If you find yourself relying on technical and prescriptive descriptions of language use, isn't it perhaps a good idea to think about what exactly you're trying to convey?
Maybe your colleagues perceive that they are being asked to study a bunch of off-topic material. Is reading RFC 2119 really the most productive use of their time?
If they can't be bothered to read and comprehend the two pages of RFC 2119, preferably in an hour or less, it raises grave doubts about their capacity to operate in a technical capacity. We kinda have to do a shitload of reading and understanding to know how things work - at least that is what I find myself doing most of my time.
I think asking for RFC compliance is asking people to pay too high of an up front effort cost for what you are trying to achieve, unless you really are writing standards and not sketches of features.
What is the problem you're actually trying to solve? People not implementing to spec? That's seldom solved by changes to language, and more often solved by an engineer getting asked to fix an incorrect implementation.
I agree with the author that writing is one of the most undervalued skills for SWEs, but for a completely different reason - it forces you to reason things through properly, even if nobody else will ever read what you write.
It's the same phenomenon of "rubber duck" software engineering, or when you start composing the very rigorous email asking a question of another programmer, then find you've answered your own question before you complete it.
Also, the same general skill for editing text is the same general skill involved in refactoring. You're trying to capture the same semantics, but with a cleaner, more easily digestible structure.
Static types are only one part of reasoning through things properly. Rubber ducking or composing that question to a colleague forces you to think of the entire logic and structure around it, etc. Types won't fix that.
This is so true. It's like the old truism about how the way to really truly learn something is to have to explain it to someone else. Literally just going through the process of articulating something, just putting it into words, is an amazing tool for revealing all of the missing pieces and inconsistencies that would otherwise be implicit.
Until you put something into words, one way or another, then it's just a fuzzy blob of assumptions and halfway articulated thoughts. The better someone is at writing, the better they're able to articulate their thoughts, even if it's just to themselves.
>Writing a couple of pages of design docs or an Amazon-style 6 pager
While we are on this topic, how does one design things? I am very new to this and would love some references. Mostly I implement other’s design in code but I have never designed anything myself.
I am always fascinated by the idea of writing an RFC like document but even that seems a little too far fetched for me as of now.
I'm not the poster you're responding to, but for me in my career, I originally tried to design things in more detail up front and write a lot about how it would work.
After many years in the industry, I've actually found that it's better to quickly prototype the various "big pieces" of whatever it is you are designing and learn the constraints of the space you are in first. (You're never going to get everything right with that first attempt at a design.) You can write documents up front explaining what you think your code is going to do, but I would actually not recommend going into too much detail because you only really learn about the problem space you are in by doing.
In terms of a document, keep the initial design light and explain your assumptions, what the technical constraints you face are and how you plan to mitigate them. This is mostly to share out with other people to see if they have concerns about the approach and if they have ideas to help with the process.
+1 to prototyping. Having 100 lines of python that does 20% of what you want your full component should do is probably more useful than a 10000 word document outlining 95% of what your component should do. You can lie to yourself in writing but not in code.
That being said, documenting in horrendous detail your actual requirements and your assumptions about the state of the world is more useful than either of the above. When your PM says they want something in "real time" do they mean like RTOS, seconds delayed, or "twice daily" (since the old system was a monthly batch!)? Is it ok to assume the system is 99% correct instead of 100%? Is it ok if a user sometimes gets a duplicated notification?
These types of requirements and assumptions can affect the complexity of a project 10x if they are not handled properly.
Exactly. Prototyping reveals a lot of engineering constraints that you cannot see just by designing at a high-level. I've been bitten too many times by thinking something is simple because I designed things at a high level (without prototyping) only to find out there are hard constraints as soon as I start writing some lines of code.
I don't know if this is a common technique but I actually like to do a "big bang" type of prototyping where I build out the major pieces all at once to see what the general look and feel of the system is. From there I can make a way more informed decision on what I need to do versus something superficially high level.
For me, the most important thing from early designs is answering the question "what are the unknowns and what are the risks of this project?" and figuring out the right path to remove the unknowns and reduce the risks.
> You can lie to yourself in writing but not in code.
You can certainly fool yourself in code, and think you have the solution, or part of it, when, in fact, you do not. If this was not the case, prototyping would be meaningless, as you could only write correct solutions.
I would advise abhishekjha to try thinking one or two steps ahead before starting to write the corresponding code, and to pay particular attention to where it does not work out as expected, because without practice, one is unlikely to advance beyond trial-and-error programming.
This is a good point. Some of the techniques that I employ today (prototyping at a large scale) are ones that I can employ simply because I have experience and can see ahead to what potential problems there are in various designs. These things aren't obvious to a junior developer and letting them get too far with a prototype can be dangerous.
It's a lot of writing and rewriting. I usually start off putting everything I think I want in the spec into a text document without worrying too much about logical consistency, then leave it overnight, add more things, leave it overnight, reshape, etc. It's important to take a long break after hitting a stopping point so that you gain some perspective. It's also good to solicit comments from your network, although that tends to be as difficult as finding code reviewers, so YMMV.
You should also write a reference implementation, because actually implementing something will expose a lot of problems in your assumptions, and it will give other implementers something to test against.
Generally, it's 3-6 months from inception to release of a smaller spec if you want it to be solid.
Actually, you could follow along with a couple of specs I wrote since I have a git history of them:
I think a lot of mature RFCs are based on prototypes. In my experience, prototyping is the first step in design; I know I've seen "designers" and "architects" hide that they prototyped something before writing the document they've been asked to. I know at least one did this to give the impression that they were able to express it fully-formed from whole cloth.
Sometimes you can get away with documenting a design based on prior art, but without creating your own prototypes.
For the most part, rather than the first, good design documents are the the second or later expression of a design.
Added: I think this ties into what jsty is saying. Good designs tend not to be the first iteration of an idea, regardless whether the iterations were intentional design, or refactoring.
IIRC, Joe Armstrong (RIP) was a firm believer in the "write it once, then throw it out and rewrite it at least once" pattern of development. I think that whether you're writing a design document or a new version of some portion of code, you are refining a design, and that tends to help.
Start off by writing down a clear goal of what you're trying to accomplish. This is pretty much the first thing I do when I write any document in fact.
Then figure out what the requirements are that help you meet your goal and write those down.
Once you have a goal and a set of requirements the design is usually pretty easy.
I agree with your point and I also think English is imprecise. It's great for socializing and flushing out ideas but it can also give one a false sense of confidence.
Really there's a general point here I think: up front, careful reasoning (which should eventually excogitation in English or math or code) not only helps prevent mistakes but it also produces documentation and reasoning collateral.
This resonates with me. My writing is clear and concise, I'm proud of it, and it pays off because I can communicate effectively.
I'm not sure I agree with the "undervalued", in so far that I see a _lot_ of people who are not able to write clearly, and they get ahead and along just fine. Many executives who I worked with wrote terrible emails (sometimes they leave out the negation, so I'm guessing whether they mean X or not-X), and they're super successful, in so far as their companies are successful / they are in high positions.
Sometimes the Amazon protocol comes up (before a meeting, the organizer submits the topic in writing, everybody has to read it before), and I always cringe - in my experience most people just can't write a clear 2 page document [or can't be bothered]. I would love it tough.
I wonder if they have a junior person that does/did the writing for them.
Reminds me of a story about fighter pilots from World War 2. Some of the best fighter pilot aces had, at best, average vision. Their coping strategy for this was to find pilots who weren't as good at dogfighting but had excellent vision as wingmen.
Both parties benefited since the better pilot could spot enemy planes earlier and the lesser pilot got to fly with an ace and occasionally get kills they wouldn't have gotten otherwise.
I recently got to ride in the co-pilot seat of our company plane and it was a neat experience to see everything and listen to the radio chatter and the view was amazing to watch the sun rise and the moon set at the same time.
He showed me how as a fighter pilot he was trained to spot other aircraft.
When one would show up on the radar he would point and be like see that plane over there? I could never see it until we were very close and I have great vision and no glasses.
After a few times of this game he then said, "Now when you are looking for another aircraft you don't focus on where it is, scan your eyes left to right horizontally".
Now I was able to pick out the what seemed like 1-2 pixel dot in the distance by not trying to focus on the dot but look at everything else and your brain somehow figures out the anomalous pixel/dark spot against the horizon.
It reminded me a lot of when I was a kid bird hunting how my dad would try to point at the partridge and it was the same game. You try to focus directly at them and it was hard to see them in the brush, but scanning your eyes back and forth helps make them pop out and be visible.
Actually there is some vision science behind this phenomenon. Your fovea is what you use to focus on things and it's got lots of cone cells that are good at picking up colors and specific details but are not so good at picking up motion. The rest of your eye though has tons of rod cells that effectively see just black and white, but are really good at doing motion detection (mainly to recognize predators and prey in your peripheral vision). So instead of trying to use your fovea to find the plane (which it really sucks at doing), you instead keep your eye moving which exposes much more of the scene to rod cells and let their natural motion detection abilities go to work.
> Only a small part of the retina, in the centre and called the fovea, can generate a high-resolution image. This is why we need to look directly at something, by moving our eyes, to see detail. The rest of the retina contributes to our visual experience by adding the peripheral detail — hence peripheral vision. Peripheral vision cannot resolve detail, which prevents the brain from being overloaded with too much information, but it is very good at detecting movement.
> Well, first, it is an unfortunate fact that if you are converging on a given point with another vehicle at the same speed, and assuming that you are both traveling in a straight line, then there is no apparent movement noticeable by the occupant of either vehicle. That is, to the driver of each vehicle, the other will remain in exactly the same position in the windscreen up to the point of impact. There is no relative movement — so our peripheral vision is not suited to detecting it.
> Now for the really interesting part. When we move our head and eyes to scan a scene, our eyes are incapable of moving smoothly across that scene and seeing everything. This makes perfect sense: just like trying to take a picture without holding the camera still. The image would be blurred. So, our clever brain overcomes this by moving our eyes (really fast, remember) in a series of jumps (called saccades) with very short pauses (called fixations and it is only during the pauses that an image is processed. Our brains fill in the gaps with a combination of peripheral vision and an assumption that what is in the gaps must be the same as what you see during the pauses.
> I wonder if they have a junior person that does/did the writing for them.
Many senior non-technical people have a "technical assistant" or similar, a talented generalist who helps wrangle the thousand different technical things the non-technical person needs to deal with.
Afaik in "modern times" at "modern companies", ie. startups, everybody does their own emailing. I worked at Facebook, maybe Zuck/Sheryl has somebody helping them with email (I don't know), but they're obvious outliers.
I meant more in the sense of "They have other people write and then send the important email/docs etc" and not the "hey, can you help me write this email".
I've helped several managers over the years write emails and I'm pretty sure they didn't then go tell everyone "Yep, I had help with this email" so I think it be surprising to some folks how often this happens.
Agreed. Sometimes its even the other way around. You could be an awful engineer from a technical angle, but if you can write good blog post and shiny docs, the powers that be (those who don't look at the code) will think you're awesome.
Still, the skill is insanely valuable. As someone who's not a native english speaker/writer, I can manage, but it takes me 5 times as long to do something less than half as good as my peers, yet I always find myself needing to write a new page of doc, a wiki/blog post, etc. If I was better at it, I'd be much, much more successful.
>Sometimes the Amazon protocol comes up (before a meeting, the organizer submits the topic in writing, everybody has to read it before), and I always cringe - in my experience most people just can't write a clear 2 page document [or can't be bothered]. I would love it tough.
At Amazon the protocol is to read during the start of the meeting. Typically this can be the first 30 mins of a 60 min meeting.
The more experience I get as an engineer, the more time I spend writing documentation, proposals, tutorials and the like.
This article is absolutely spot on when it points out that these skills become increasingly important as the size of an engineering organization grows.
The biggest challenges in engineering at scale (scale in terms of complexity and size of the team) are around communication. Good writing is how you scale your communication, especially if your team aren't physically co-located.
I don't think software engineers talk about or think about how to improve technical writing nearly enough.
I'm more on the operational side, but I have the same experience. I easily spend 50% of the time I spend on technical topics documenting my findings.
To us, good, structured documentation and/or well-written tickets are a crucial part of delegating a task. Practically, it is part of my job to figure out and solve hard and architectural problems, around once per problem. Then I can document it properly. After that, the bulk of the team should be able to solve this problem.
And this is producing value for our customers, because well-documented standard tasks are resolved faster. I might be unavailable due to some critical problem. But if it's a documented standard task, one of the four other guys can pick it up and resolve it quickly.
Absolutely. And if you ever want to strike out on your own and start your own company (especially if you want funding for it), writing well is critical and can't always be outsourced.
The problem is that many organizations prevent their IT/engineering departments from professionalizing in a way that would allow for this. "We need a month to iterate over requirements and specification" can land like a lead balloon in any project management meeting, because the _non_-engineers don't see any value in it.
When you try to explain to them that implementing a new system they want isn't as simple as installing new kitchen cabinets.
Try to explain that it is like when you install a kitchen cabinet and then open up the door and it leads to an entire new kitchen cabinet set which also needs to be worked on and that cabinet also has it's own kitchen cabinets that need redone as well.
A lot of times (at least where I work) management has a hard time seeing all the layers in the IT systems they use and what appears to them as a simple surface fix/change isn't always the case.
My tech-write wife says the Engineer-writer fault she most often encounters is the 'mystery story'. That's hiding the lead down at the bottom of an argument. Because Engineers like to show their work and don't want to 'give away the ending' until they've proved it right.
So put the conclusion right at the top somewhere! Sometime its as simple as putting the last sentence of every paragraph at the beginning of the paragraph.
It's about emails, but I like this article[0] about how topics are covered in the military (where I imagine clear communication is important). "Military professionals lead their emails with a short, staccato statement known as the BLUF (Bottom Line Up Front). It declares the purpose of the email and action required.". I find this helpful..
The BLUF is exactly analogous to what the internet hivemind calls the tl;dr (too long; didn't read). I almost always see the tl;dr as the last line of a long post, when really, it makes a lot more sense to lead with it.
Seconded. I always put TL;DR at the beginning if it's meant as an actual summary. I sometimes put a TL;DR at the end, when it's meant as a humorous summary.
> I think it's less about "give away the ending" and more about construction, and wanting to avoid making a claim just from authority/status.
I agree, but maybe that style of writing has evolved for good reasons? In engineering, it seems to be a common personality trait that when presented with conclusions first, we tend to formulate reasons contradicting the conclusions, and then dig in on those reasons, to the detriment of trying to follow the explanations that follow.
In the military, on the other hand (which has been cited as an example of "bottom line first" culture in this thread), people seem more inclined to follow orders.
Anecdotally, in my limited time in the military, I had the opportunity of observing both kinds of personalities, and they did NOT mesh gracefully…
I really love this blogpost which discusses these two personalities, in the context of "corrections from strangers on Twitter".
Some see corrections as "sharing information"; others see making corrections as asserting status/dominance which disrupts social harmony.
https://status451.com/2016/01/06/splain-it-to-me/
People who design things, how do they make sure that what they are proposing is doable because we won’t know until a group of engineers finish the project and it goes into maintenance?
This is something that I struggled with, good writers can build a story that reveals something over time. I'm not a good writer, I can't build stories like that, so I just have to lay the point out and support it after 5th grade form essay style.
There's a reason technical writing has the term 'technical' in it. It should be different from how one would writes for a casual audience (who are reading for fun). When reading as a hobby the mystery of where the story will lead to is part of the fun. But when reading a technical document you don't want there to be a mystery, you want to get the message as soon as possible. So it makes sense to have something upfront that tells the reader what the next couple sentences are about. I wouldn't see it as mediocre writing.
I noticed the article appears to contain a single point of evidence supporting its main claim:
> Don't take this advice just from me. Take it from others, like employee #8 and now SVP of engineering at Google, Urs Hölzle who also says that writing clearly is an important superpower for engineers.
The link goes to a LinkedIn page with a brief quote captured in raster image format. This is weak evidence for a topic that will certainly be met with strong resistance from the target audience.
The author could make a much stronger case by interviewing a few people at top companies specifically on the topic of engineer writing. These people should be in a position of making promotion decisions. The author might coax out of them illustrative anecdotes that show exactly how poor writing skills can keep an aspiring engineer down.
How much money in lost wages is my crappy writing costing me? What are my job prospects if my writing doesn't improve? What exactly will better writing allow me to do that I can't already do? These are all questions that demand answers (and evidence) from people with 10 other things they might be doing.
Another idea: what studies (if any) have been done on the correlation between writing quality and promotion within technical organizations? For that matter, how does one objectively measure writing quality? After all, you're much more likely to improve something you can measure.
A hallmark of good writing (of any kind) is ample evidence to support claims. Engineers and scientists are a skeptical bunch, and so this point applies even more to technical writing.
In a past life I helped optimize >$1b of online transactions as a CRO professional and learning to objectively "write well" could be quantified in two ways:
1) Message Density - there's a great quote attributed to Mark Twain that nails this "If I'd had more time I would have written you a shorter letter".
In practice Jeff Bezo's push to making executives build "4 page memos" for meetings outlines this idea clearly: "the reason writing a good 4 page memo is harder than "writing" a 20 page powerpoint is because the narrative structure of a good memo forces better thought and better understanding of what's more important than what, and how things are related"(1)
2) Message Accessibility - Making your message broadly accessible is a good forcing function to writing clearly. An easy "hack" in this department is to utilize the "gunning fog index"(2) which is a structured way to estimate "the years of formal education a person needs to understand the text on the first reading" and there are many tools online that can spit out a score.
Amazon is obsessive about this stuff. I'm surprised the article never mentions it.
There are internal classes offered on writing better documents (and it's a great class). There's videos, guides, documents, everything. Writing well at Amazon is key to a successful career here. Got a project idea? Write a very good 1-pager explaining it and you've got a much higher chance of it actually happening. Want to share a design? Write a 6-pager (often 10-15 pages with appendices) explaining what, why and how you're going to build the system.
I've been in meetings that start with 15 minutes of silent reading, then 45 minutes of discussion. No PowerPoint presenting.
It's very weird for newcomers, but I don't know anyone who finds that it isn't better than the alternatives.
> I've been in meetings that start with 15 minutes of silent reading, then 45 minutes of discussion. No PowerPoint presenting.
I wish this could happen where I am. No one wants to bother reading anything ahead of the meeting to be prepared for a discussion. Then the same people don't have the patience to let the group review the material during the meeting before starting the discussion.
This is exactly the point of the silent reading time. Stop lying to yourself and others by saying you'll read ahead. You won't. No one will. Or worse, everyone but one person will and he'll have "skimmed it" and then ask questions that are on page 2, wasting everyone's time.
If you want to bring this to wherever you work, I encourage it. All you need to do is lead the meeting yourself with a strong, assertive voice. Tell them this is what we're doing. When someone inevitably complains just ask them to please wait to ask questions until everyone is done.
I WANT TO read ahead, but nobody tells me even what meetings are about despite having company wide meetings on effective meeting and the first point was about setting agendas and seating meeting goals and topics.
I've found just declining these no-info meetings to be an effective way to combat the time loss. It's most constructive to send an email alongside saying something like "please share an agenda or materials for this", but that can vary based on context too. And you can even decline after that happens: "Thanks for the details. I'm sorry, but I cannot take the time away from X right now to attend this. Next week may be possible."
If somebody really needs my time, they can tell me why -- or go through my manager which they should be doing anyways.
You say that, and it sounds like it ought to work, and yet…
I had to do that to a co-worker, and all I got back was "Product Foo". Okay, but what about Product Foo? Blood from a stone, every damn time, and it wears me down.
Well, that kind of reply is just rude, and personally I'd probably ignore it and leave the meeting declined. If it comes up later, "Your reply about the meeting? No, I don't think...oh, I did see it, right. I assumed there was more info coming; I'm totally focussed on $X right now, you know."
"I'm sorry, my responsibilities don't leave me any time to discuss Foo in general terms at the moment. If
you really you need me to, please raise it with $manager, and we will reprioritize my duties."
People won't read ahead, so you all have to get up to speed on the doc, during the meeting, then some jerk manager who is always late comes in and makes us all repeat the same discussion. The meeting ends up taking all the time just to cover what is in the doc but no decision gets made because we ran out of time.
It's a bit fuzzy whether people from CS backgrounds acquire this skill organically, but the style guide / format of the x-pager docs felt very familiar to scientific publishing.
The main value of it felt that enshrining factual objective information and basing all discussion around that.
I like this idea on the surface. The flipside though is that if everyone's reading the doc for the first time right before discussion, it doesn't allow for much depth of analysis. Do you also send the materials out beforehand?
You'll be amazed how good people at Amazon become at reading with experience. The discussion comments that come out are often fabulous.
On the other hand, I am indeed able to add a lot more value as a reviewer if I can read the document ahead of the time. So whenever I am the prime reviewer, I request the document to be sent one day ahead of meeting even if it is incomplete at that time.
Perhaps in a competitive/demanding culture, this is the best you can get.
Besides, very few people in decision making positions have time to study all the prep material beforehand. I sure as hell don't do that when I have back-back-back meeting schedules.
That imposes two problems: that I am limited to about 15 minutes of research time (limiting depth and basically eliminating "phone a friend" consultations) and it requires that one permits laptops into the meeting.
Nevertheless, I'm a supporter of the approach and have introduced it into the most important review meetings that we hold in my group. (We do bar laptops and other electronics, other than video conferencing equipment.) Results after 18 months seem quite positive on balance.
Generally people need some time to ponder new input in order to grasp edge cases, work through implications, identify unspoken assumptions, and so on. Some extraverted folks are happy to "think out loud" in a group, but even then it's too easy for a conversation to move quickly past a particular point that deserves more time.
If you search for "amazon narrative writing style" you'll find all kinds of articles.
The way that I personally explain this to new Amazonians is that I want their documents to tell a story. Now, I'm in engineering so the the story is going to be about some kind of highly technical topic, but it should start with an introduction, and it should lead the reader to the point that they have a pretty solid understanding of the problem space. If we put a document in front of a leader who has never even heard of our team before they should walk away understanding what the problem we're trying to solve is. That's part of what makes it so hard -- writing for an audience that might not be familiar with ANY of your internal jargon.
The documents must also be quite dry; they should avoid unnecessary adjectives, opinions should be called out as such, etc. Don't say, "high throughput," say, "72k TPS." That kind of thing.
Honestly there isn't anything that you couldn't get by simply reading and applying the advice from
"The Elements of Style" by Strunk and White[1] and "On Writing Well" by Zinsser [2].
The primary philosophy is that if you can't write well, then you haven't thought it through. The act of writing is an act of reasoning.
0. Practice in a strong feedback loop. This applies for anything, not just writing.
1. Ruthlessly reduce your sentences. Repeat until you can't eliminate or combine any more words.
2. Avoid adverbs. Use "dashed" or "sprinted" instead of "ran quickly". Learn more words.
3. Avoid weasel words like "should" "could" "might". Take a stance and give concrete reasons.
4. Use concrete data over descriptors. "+5% profit" over "increased profit".
5. Write in active voice. Look up the "by Zombies" trick.
6. Use the simplest word that maintains your meaning. No one needs to use the word "utilize".
#0 is correct. I'll recommend this piece on S&W [1] and specifically on point #5 [2].
These style guides, especially points #1 through #6, came about from bureaucrats who were essentially filibustering or otherwise obfuscating in their writing.
The root problem there was not the long-winded writing, it was their intent to hide bad things.
If you can make sure you're not carrying water for corrupt officials, you best strategy is to try to write natural prose. Yes, do look for wordy phrases or cliches, but don't obsess over adverbs or the passive voice.
Geoffrey Pullum (author of the language log article you link to) also has an excellent set of videos explaining why most advice about passives is bunkum.
I found "Style: Toward Clarity and Grace" [1] by Joseph M. Williams to be more informative than both of these recommendations, but YMMV. There is a newer version, but I haven't read it.
"Note: GeekWire’s Todd Bishop prepared this memo in the traditional style of an Amazon ‘six
pager’ — fictional press release, narrative, FAQ and appendix — for Amazon Consumer CEO Jeff
Wilke and the audience at the GeekWire Summit, where Wilke will speak Oct. 10, 2017."
- Some light style rules about having no qualifiers e.g. words like "really significant" were banned
- Keep language super concise and non-flowery. Don't try to sound clever, Keep It Simple, Stupid for language basically
- Structure arguments a bit like the Minto pyramid[0] was another one I was told while there
- No one cares how much work or effort went into your doc, or how clever it is, only the final artefact of your work/thought should make it into the doc no matter how concisely you can express it
Your boss, or his boss. They are a gate keeper, in the sense that they can choose whether or not to fund your idea - or, if they are already on board with funding your idea, they need some concrete document that they can show to their peers, to get them to help you/agree with this prioritisation.
I had the same initial reaction, but then again...doing it during the meeting, always, ensures that all participants are at least talking about the same thing. I’ve been in meetings where it doesn’t become clear until very late that someone is bullshitting and has not actually read the materials, or read them so lightly that their comments/opinions are not well directed. This is, imho, much worse than making sure everyone is on the same page. Since everyone is presumably going to need to read the docs at some point anyway, incorporating the activity doesn’t really seem like a waste of time to me.
I've been writing software professionally for about 20 years. I'm not sure I've ever been to a meeting where most of the attendees have prepared by reading relevant materials including documents attached to the meeting invite. Because of this experience, I have a very different expectation. I attach documents to the meeting invite so that people can know where to find it for reference during but mostly after the meeting.
Sometimes there is no clear or a weak "chair". Furthermore, if the bullshitter is influential enough that you don't have time/capital in-meeting to call their BS? That's why BS is successful.
I see the Amazon approach as an augment to the chair to keep the discussion on-topic. If it's not discussed on the paper, the burden is on the dissenter to provide info / present credentials to rebut.
This process is designed to ensure that the docs have been read and have been freshly read. I think of it as moving the time and effort into a defined and nearby time, and it's far from a "waste" of time, IMO.
Only somewhat related here, but we recently did a QP where our team came in without previously breaking epics into smaller tasks.
One argument is that we could've done that outside of the meeting, in its own meeting. But that actually wouldn't have saved any time, but would've probably cost more. Basically, we set aside the afternoon to accomplish the task at hand. If we had broke it into multiple days, there would've been memory debt we'd have to refresh.
As an engineer, I feel that requiring pre-homework for a meeting can be detrimental. As other posters mentioned, going through it all together in the scheduled meeting ensures that everyone is on the page. Additionally, it means that an hour long meeting doesn't actually require an hour and a half of my time, so I can better judge and plan my schedule.
Amazon is also big on "mechanisms over good intentions".
Asking everyone to please do these actions before the meeting is a good intention. Everyone wants to, but you know things happen and well I skimmed it but I didn't really have time and now I'm going to ask questions that page 2 answers clearly because I didn't read it. Everyone's time is wasted.
Forcing everyone to spend 15 minutes right now is a mechanism. It's much more effective.
Especially for those who work remotely, I (English is my third language) can't overstate the importance of deliberately working on writing skills. As remotees, we are often judged by our words, whether we like it or not. A couple of recommendations:
• Many here might've already come across it, but is always worth bringing up: William Zinsser's, On Writing Well. In which, he urges us to write with "clarity, simplicity, brevity and humanity"; tells us "the intangibles that produce good writing—confidence, enjoyment, intention, integrity"; reminds us to "remember that what you write is often the only change you'll get to present yourself to someone whose business or money or good will you need"; and much more.
• The equally excellent book, Clear and Simple as the Truth[2]. In this rigorous work, Thomas and Turner describe a style of writing that rests "on the assumptions that it is possible to think disinterestedly, to know the results of disinterested thought, and to present them without fundamental distortion. In this view, thought precedes writing". And the book also has a chapter that is aptly titled, The Museum, a "guided tour through examples of writing, both exquisite and execrable".
The second book, I suggest to slow-read it over a period of several months to digest it (and perhaps even do the exercises in the chapter titled The Studio, if you're a non-native speaker), not least because, as a certain Roman Stoic urged us, to read attentively—not to be satisfied with "just getting the gist of it".
I'd also recommend "It Was the Best of Sentences, It Was the Worst of Sentences" for some easily digestible writing on how to write easily digestible writing. It's probably one of the most useful type of writing skill to have as an engineer.
I used to be a huge proponent of learning to write well as the most important skill an engineer can learn.
Now, I think it's the second most important skill.
The most important skill is sales.
The key value of writing well, in a workplace environment (or other environments, really) is to convince others to agree with what you're proposing. Convincing people that something they don't initially understand or trust is going to be a win for them is a sales problem. Clear writing is only a means to that end.
There's nothing smarmy or dishonest about sales. Misleading sales is bad sales. The best salespeople are focused on fulfilling the customer's needs, not selling the product. The product sells itself once the customer understands that it fulfills their needs and offers them real benefits relative to the expense. And expense isn't just money. It's time. It's risk. It's learning curves.
Customers often don't understand their own needs very well, so a big part of sales is helping the customer understand their own problems, in order to provide valuable solutions.
The engineer who can really dig into requirements, really get to understand the customer and help the customer understand their own needs, and then offers a working solution, with clearly stated benefits and clearly stated costs, will do far better.
It's not about sales it's about how people think, act, and make decisions. I would bet that most any book on sales will invariably touch on at least some of the topics covered in this book.
It's a fun read and I promise you will start to see these patterns being used in everyday life in verbal and non-verbal communication.
Start with How to Win Friends and Influence People, by Dale Carnegie. Ignore the cheesy-sounding title; this book was written in the 1930s and has been in print continuously ever since, which speaks to its effectiveness. I also recommend To Sell Is Human, by Daniel Pink (and all of Daniel Pink's other books, as well).
I disagree that this separate from writing as a skill.
I don't think you can characterize any writing as "good" if it fails to persuade the reader to care about the author's message. The audience for writing is humans and the author has to get their message to stick in that human's head. A piece of text that is precise, terse, grammatically correct, and completely uninteresting or persuasive is not writing, it's merely a catalog of facts.
But I agree totally that the "get the person to care" aspect is a fundamental part of writing well that is very often overlooked in technical writing.
They're both important. The question is, which is more important? Well, what are we measuring? Success in goals. And which is more likely to achieve goals... good writing with poor sales, or good sales with poor writing? I'd argue the latter, for a variety of reasons.
That sounds like a contrived scenario to me personally. Most programmers simply do the task that their supervisor or manager has assigned to them. Its not like they can refuse to do a task simply because it was worded poorly. They would just ask for further clarification.
Most programmers simply do the tasks assigned to them, because most programmers don't know how to sell!
If you can sell, then you get to decide what you should be working on, convince your manager (and team leads, and other managers, and business teams, and anyone else who might be a stakeholder or shot caller) that it is in their best interest to have you work on the thing you have recommended. Note that this can't be BS... what you're recommending has to be an actual win for them. So, when you've completed the task you sold them on, they see you as a visionary and successful technical leader. The trust that creates will allow you to pick bigger, more ambitious things to work on.
Of course, this assumes that you want to take control over your own work. If you're content just doing what you're told to do, then keep on doing that.
Understanding the problem domain, i.e. what the customers really want and need rather than just what they specifically ask for, will help any software engineer do their job better. Only then can you suggest alternative solutions that solve the real needs vs. patching one requested item after another that are all half measures to solving the real problems.
I don't know what scenario you're envisioning, but I'm envisioning a scenario where the task a programmer works on is assigned to them by a supervisor, a project manager, a lead, a project planner or whatever other similar designation companies have.
The idea that non-trivial projects get built by engineers "selling" their ideas to each other doesn't align with my experience or even expectations. As a manager, I want my best developer to work on certain tasks, and not a junior developer. I don't want someone not familiar with the domain or technology to pick tasks which they have a high likelihood of failing at, etc, etc. Nothing controversial. Simple basic common sense.
Companies have ways to escalate concerns programmers have about the tasks themselves. And it could also be that programmers are invited to comment on the road map/big picture. But that is something different.
It circles back to my point, though. It doesn't apply to them because they don't try to sell their own ideas. If more engineers took the reins of their own work, I think they'd be happier and more successful.
Many tasks are poorly defined or aren't solving the real problems the customer has. This is the classic problem of a customer asking for something very specific then complaining when it doesn't solve their problem. There are a lot of developers who deliver exactly what is asked for in this way. They would be better served by taking a few minutes to make sure they understand how it serves the customers' actual needs, not just completing another ticket.
I have kept around and distributed multiple copies of The Elements of Style, by Strunk and White, for the past few years (lots of revisions of this out there, 4th might be most recent iirc). It's like a 9$ book and the guidance is priceless.
Most of the guidance is very outdated. It's likely to confuse more than clarify unless you've taken the time to study modern resources. I prefer Bryan Garner's work, like his usage guides.
Writing well can have several meanings. I've found that hilarious bug tickets are much better received and treated than dry ones. Maybe because they get many eyeballs (of the sort that makes all bug shallow).
Here is one of the first ticket I wrote in my still current company:
Then God appeared to wazoox and told him: "You will not spread your software on the face of the world without properly testing the new features, so as not to get into trouble with a rarely used tool that proves buggy with an important customer. I said, and so be it." So it was done this way, and the courageous people of the developers wrote unit test scripts, to validate the proper functioning of each new version, whereas until now they were content to test by hand and whatever popped into their heads. Then rivers of milk and honey flowed on the earth, and the customers gave them much money; then the Lord saw it and was pleased.
Instead of a clear script, the developer now has first has to wade through word diarrhea to extract meaning.
> Then God appeared to wazoox and told him: "You will not spread your software on the face of the world without properly testing the new features, so as not to get into trouble with a rarely used tool that proves buggy with an important customer. I said, and so be it."
This could have been replaced with: "First test new features before sending to customer." ... ... I think.
You do have a point but still let's look at it another way.
It's a ticket. That means that at best it's boring and mundane. The writer knows this and is trying to convince you, to sell you, on spending some time thinking about it. Granted, you should do that anyways but First test new features before sending to customer doesn't really convince you to do that. If your text was enough then maybe it should have been a check box and saved everyone some time.
All that said, there is a time and place for humor. Maybe this was it and maybe it wasn't. Dunno. Audience matters; timing matters; context matters.
Writing well can have several meanings in literature, but in professional environments I'd argue it has one meaning: Writing well is writing something clear, concise, to the point.
I worked with an engineer who wrote as you describe above ("hilariously") and it became incredibly tiring having to pick out the meaning of each correspondence. They took more time to read, and often important details were overlooked because they were hidden in a joke. I had to reply to nearly every message with my own summary: "So you're saying X, Y, and Z, is that correct?"
Humor is wonderful, even in professional messages, as long as it doesn't detract from the messages being clear, concise, and to the point.
This isn't a bug ticket, though, it's a complaint that people didn't write unit tests. Humor works better when genuinely lighthearted and not trying to slip through some criticism. Criticism probably works better when not disguised as a parable inside a bug ticket.
I do find it a bit bizarre that the otherwise smart people that I work with, with English as their first language, will often resort to writing emails and documentation like a 14-year-old on AIM. I'm obviously much more forgiving of people that had to learn English as adults, but somewhat paradoxically I find that they typically write a lot more comprehensibly than most of the native-speaking engineers.
I'm hardly John Steinbeck or Mark Twain, but I've always felt that if I wanted to be treated like a grown-up, I should write like a grown-up, and as a result I have tried to write well. I try and be understanding of typos, because those are just honest mistakes, but when an adult sends an email to me saying something like "when r u going to do this?", I get a bit annoyed.
I used to think like that (being the kid that wrote well in school). But now I'm not so sure anymore...
Been humbled too many times by people much, much smarter than me that wrote in smsesque. Have read too many apparently well-written texts that are nothing but bullshit written by ignorants.
Oh, most of my coworkers are smarter than me, so I'm certainly not trying to make an assessment on their IQ or any nonsense like that.
That said, I do think that writing smsesque (which I am going to steal for the future because I had never heard that term before) is a really good way to make yourself look dumber, especially to non-engineers. Even if my long and rambling writings lack substance, they still typically give the optics of someone who is smart. Is that the way it should be? Probably not, but I don't make the rules.
I agree. We can write smsque in a slack channel and "its ok", but it's not OK to write like that in a document sent to customers, in a wiki that explains how a piece of software works and will stay there for years or in an email aimed at winning an argument. Those would be detrimental to the company and to the developer.
> I do think that writing smsesque (...) is a really good way to make yourself look dumber, especially to non-engineers.
Maybe they do that in purpose, then?. They do not need to be admired by everybody, especially not by non-engineers. Like the very rich people who dress extremely humbly, with torn-down clothes.
My experience is that it's not on purpose and it's not signalling of any kind.
First, let me be clear: I'm lucky that I'm surrounded by smarter people than me. Almost all of my coworkers are incredibly intelligent people, can troubleshoot and code circles around me, and understand teamwork and building reliable software way better than me. It's a great situation to be in, because I have plenty to learn from them.
Unfortunately, they don't write very well in their native language (which is not English, by the way). They always ask me to proof read what they wrote. Full of typos and unclear sentences.
They also seem to be less well-read than me. Many don't read fiction at all; if they read anything, it's mostly books on tech. It's like their brain power is directed at other pursuits, and as a consequence their writing skill suffers.
No they do not. I've seen a LOT of smsesque text that come from all sorts of different people who i'm 100% they are not trying to "appear dumber". I do not know why people do it, so i assume laziness. Smart people can be lazy too.
In the end all writing or speech is about communicating an idea.
My opinion is these people have learned it doesn't matter. If an idea can be conveyed in smsesque and still get the point across while being quicker to write, then why not?
I have a feeling power/authority/expert status matters here because the listeners will power through unclear communication just to gleam a glimpse of the underlying idea from this idol.
i am reading all these replies and i found them really interesting. i think the same people being annoyed by sms-like writing, would get mad at me not using proper casing with my sentences.
at the end of the day, i think it does not matter. i am not writing a book or an article. and when i am texting, i would rather keep it short, sms-like.
i would like to understand, truly, why people get mad at such things. it has nothing to do with being disrespectful or anything.
last time someone was mad at a particular emoji. i believe it's the next form of shortening messages. and guess what? i would rather have an emoji than type a sms-like message. maybe some of us just like being efficient?
Emoji are a terrible insult to the written word. They're also an affront to imagery.
Standard images, at least, are the same image everywhere. A grid of pixels is a grid of pixels.
Emoji, however, vary from platform to platform, so what you pick may well not be what your reader sees. In some cases that may matter, in others it may not.
Furthermore, some people construct new meanings and usages for emoji that do not align with the actual descriptions from the Unicode standard. You'll only realize this if they tell you, of course. I had one of those moments with my wife a few weeks ago.
I'm still (irrationally) upset that emoji are in Unicode. They're ambiguous, ill-defined, and they are certainly not characters in the multilingual support sense of the word.
Do I use them? Yes, grudgingly, and I hate myself a little bit every time I do it.
Emoji are part of the natural oscillation of written language history between ideographic and phonetic. It has happened several times in history, there's nothing to worry about.
Yup. Anti-signal-signals are a thing. "I don't want or need to care how hard it is for you to understand me, so I'm not going to give any thought or effort to making it easier for you" is certainly a kind of signal.
Also, in an industry where “fake it till you make it” is the rallying cry, one shouldn’t appear dumb, lest one actually becomes dumb (at least in the eyes of their colleagues/superiors/reports/clients).
This may not apply as much to written language, but there are benefits at times to pretending to be more ignorant or dumb than you actually are. My father was actually a master at this. He was brilliant in his own ways (not the academic sense, but mechanically and socially brilliant), but had the persona of the "dumb hick" down completely. People would underestimate him, sometimes try to take advantage of him, then he would gently show his competence and they would quickly backtrack and essentially give him whatever he wanted. It's obviously manipulative, but was often a way of catching people in their own trap. Think car dealers trying to cheat him, salesmen, etc. I just can't pull it off as well without seeming fake.
I'm not sure there is validity to either appearing smarter than you are or dumber on a regular basis though, particularly with people you work with. Integrity is a much more important attribute to me in coworkers and employees than either feigned competence or feigned humility. Genuine competence or genuine humility are different matters though of course.
Exactly what came to my mind as well. A lack of care when you write can signal that you do not know how to write well, or it can signal that you don't care to write well. Neither of these are signals I want to send, both harm my reputation.
It can also be a signal that you're too busy to write well in that context.
There are two elements to writing well. One is the efficient communication of content. The other is communication of social register, relative status, and power relationships.
Hitting the right social register is an impedance matching problem that depends on the target audience.
If you go too high you risk sounding snobby, pretentious, and condescending. If you go too low you won't be credible.
People often assume this means that if you lard your verbiage with orotund circumlocutions and vague implications you'll be hitting those high register top notes.
But in fact social register doesn't map neatly to grammar/reading age/vocab.
SMSspeak in an email can - ironically - hit too high a social register because you're implying you don't have time to write a more detailed and conversational response, and you're not making the conversation a priority.
This is orthogonal to any actionable message content.
If that's the case then it's kind of mean, isn't it? They know that I'm a grown-up, and are writing to me like a child, effectively talking down to people.
No one is going to give you major adoration for using the word "you" instead of "u", or "are" instead of "r", so I sincerely doubt they're doing it as some sort of humbling thing.
Don't write long, rambling, run on sentences, they confuse the reader. As a side note... it is always fun to read pro/con paragraphs for ballot measures and even Congressional legislation... they are masters at expert ambiguity.
Writing well doesn't mean you're smart, it just means you've put some effort into writing well. It's an exercise in empathy and consideration for one's readers, and crafting tolerable sentences with reasonably-normal usage is just the start of it. Ensuring you're writing something worth reading, with every sentence and every word, is another. "Bullshit written by ignorants" tautologically falls short of that, however fit their writing is otherwise.
Limiting this to written technical discussions, I don't get uptight about misspellings, typos or grammar errors, so long as I can unambiguously parse what they want to say. What bothers me is that txtspk is almost always unclear and frustrating. That tends to lead me to try to find folks who do write clearly, just for efficiency.
I will say that I do judge on written proficiency. Again, I don't care that much about form (although in more formal writing, mistakes are signals), I care about clarity of thought and ability to convey relevant information. Completely apart from interpersonal factors, programmers who can't write in a human language tend to be bad at writing in artificial ones.
> Been humbled too many times by people much, much smarter than me that wrote in smsesque. Have read too many apparently well-written texts that are nothing but bullshit written by ignorants.
I cannot imagine why you found them humbling. Ignorance or lack of skill are forgivable, but poor writing by someone who could do better but just doesn't care about their output or their audience is just lazy. If someone who could do better cannot be trusted with something as simple as writing a coherent message, why would you trust them with anything else?
Because they were humbling to me and I learned a lot from them, despite their clumsy writing style (not because of their writing style!).
Imagine that you have worked several weeks on a problem, you are very proud of the code that you created that solves the problem elegantly; you document it with well-written, correctly punctuated comments and documentation. Then the smspeaker looks over your shoulder and says "dude, this data structure isn't necessary here, just use a table of integers and it will be faster and the code 80% shorter", which is a self-evident statement after the fact. THAT is humbling, regardless of whether the guy writes his mails in correct english or smsesque.
I think, in my experience, that there is a middle way which Ive seen the very best use (and try to follow). Fundamentally it is not about how much you write but how well you communicate.
There is a difference in people that rattle off sms-style one liners every time, and those who know they only need one line to communicate fully.
My experience is; the former style almost always leads to an email chain where one party steadily extracts information from the other, like pulling teeth
I don't care if you write "you" or "u". I do care a lot about clear definitions in technical writing. For example, someone could mention a "system". What exactly does he mean? Is it synonymous to "the servers" he mentions in the next paragraph? Or is there an important difference?
Even worse if people do not even read the text and only look at the diagrams. Hours of meetings could be replaced with minutes of reading.
Even worse if people do not write text at all but only PowerPoint diagrams. What is the meaning of the boxes and arrows? Is it consistent?
Maybe the responsibility should be placed on the readers as well? They should demand better writing.
Please both put the units in writing and make sure they're correct! Your network does not run at 100 milli-bits per second. A byte (B) is a lot bigger than a bit (b). Mega (M) is not the same as milli (m). Term contract prices are typical per month or per year, so when you tell me the contract is "only $25K", you haven't told me anything. Tell me it's "$25K/yr" or "$25K/mo" and you've told me something.
From my experience peer-editing class papers, bad writers aren’t dumb people. Someone would have an interesting idea and explain it cogently to me in person while sounding normal and fluent. The paper would be a train wreck, but a transcript of the verbal explanation would be worth at least a B.
It seems some people just have a disconnect between text and verbal processing.
I find it bizarre that most people don't realize writing 'correctly' is just intelligence signaling too. There's no reason for it most of the time. If I can type something faster but still just as clear by typing it less-formally, I will often do so.
Yeah, maybe I should have supplied a better example, since "when r u going to do this?" is fairly unambiguous, so I suppose that that is a failure of writing on my end :).
However, I've seen people us abbreviations that are incredibly difficult to parse, even for people with English as a first language. I can't imagine how difficult some of those emails can be for people that didn't grow up with the language.
I'll take a conversational email with sms shorthand and emojis explaining a bug effectively over the business major crap emails I get 30 times a day complete with greetings, farewells, oxford commas, correctly used semi colons that don't actually tell me what the problem is or what the repro steps are.
Have we arrived at the place where we have to choose one or the other? Because I choose option 3: where people do their jobs relatively well, with some amount of professionalism (which I used to think was a necessary, but not sufficient, part of doing your job well).
I recommend taking the opposite approach. I'm in a leadership role and I model my communication after the audience. This is a social bonding technique, it results in people liking you more. This is everything from formal vs informal language, mirroring body language, and using their preferred communications protocol: email, IM, phone, face to face. Any time someone has a specific quirk in their communication, instead of being annoyed, see it as an opportunity to make a new ally by modeling after them.
>I'm obviously much more forgiving of people that had to learn English as adults, but somewhat paradoxically I find that they typically write a lot more comprehensibly than most of the native-speaking engineers.
This might seem paradoxical at first, but upon further inspection you realize that those who learn a language (as opposed to acquire it) are better at it.
I also think it has to do with the fact that in order to write in a second language, you have to more-closely monitor what they're writing, because it doesn't come as natural.
I don't know any second languages, but I suspect that in order to communicate with the native-speakers of that language, you have to be a lot more deliberate about it.
I love this quote from Thomas Mann: ""A writer is someone for whom writing is more difficult than it is for other people."
Keep at it, even though it tears you to shreds. It's worth it. It tears everyone who does it to shreds. You aren't alone in the way you feel about writing and you can do it too.
Yes, that is fine. I'm obviously not asking for someone to write the next Moby Dick when sending me an email asking for a status update. A short and simple message is totally fine, I just would be prefer that it be (mostly) grammatically correct.
That is easy to say, but it doesn't work that way. Your mind knows what you wanted to say and assumes it said that. Even when you read your writing again you know what you meant to say and you will skip over the bad grammar.
Note that this same problem exists in spoken speech. Someone will ask a passenger to "please adjust your window out" which makes no sense. What they really want is adjust the mirror out, but the brain knows rolling down the window is part of the task and confuses all the parts. Even when asked to repeat themselves they will repeat the same nonsense sentence without realizing it isn't doesn't make sense. (this problem was more common 30 years ago before power mirrors where the driver could adjust the mirror himself)
The only solution I've found is to sleep on it. Tomorrow I'm sure I will find a some grammar errors in this post, and likely something else that doesn't make sense. I just read over the entire post now though and I don't see anything wrong with it.
I mentioned earlier that I am fairly understanding of typos.
Typos are an honest mistake, and since I work with humans, they are going to make mistakes. Even using the wrong version of "its" or "it's" is ok, because at least that is an easy mistake to make.
However, when someone writes me an email using a lot of abbreviations and shorthand, like something a 14-year-old would write on AIM, it makes me feel like I'm being treated like a 14-year-old on AIM.
Do I mind if a friend does that in a text? Not at all, this is informal. But coworkers aren't inherently friends, they should be (at least in theory) adults that you have some respect for.
You have taken things out of their context. The syntax he was talking about is "when r u going to do this?", not honest typos. It has nothing to do with what you describe.
I sometimes use that when I have a low risk of typos and I am limited in my typing speed. It takes significantly more cognitive effort, and often I can just type if 9ut faster than the other way around.
Yes, i can understand if you are trying to save some SMS space on a phone because the longer the SMS the more you pay, but when writing an email you do not have such limitations.
If I had a manager send this to me, it would impress in my mind a comical and degrading image of them hunting and pecking for keys. Doesn’t conjure much respect in an industry where computers are the main tool, IMO.
Solipsism. In communication, intent and perception are both factors that affect how the parties view each other. This is what "know your audience" means.
> apparently form for whatever reasons
I already gave you the reason: they aren't communicating professionally. They do have some control over how they project their image to others. After all, they're the one writing the message.
This is getting into the realm of philosophy. According to Stoicism, one has no control over others thoughts. I personally think thats a quite valid view.
I would evaluate a message from a manager by practical rubrics.
1. Clarity.
2. Comprehensiveness.
3. Terseness.
Even those are fairly subjective, anything beyond that is so subjective it could counjour perhaps any image in someones head depending on the person.
According my my rubrics above, the managers message was fine.
As with most things in life, it's about signaling. At work I always type with correct grammar to seem professional. On twitter I deliberately don't use capital letters or apostrophes to seem relaxed. Not because I actually care (and I don't care what anyone else does), but it influences how I'm seen. I really have no idea why it matters so much to some people, other than generic "its just our culture" arguments.
It is a fairly thankless job because it's more difficult and the concept of bugs or missing features is fairly fuzzy (compared to software). But it is highly valuable, and people do notice it.
I attribute most of my open source popularity/stars at decent/good docs+examples in my libraries, like the most recent one:
Why is this skill considered "undervalued"? Could it be attributed to the gluttony of the industry for engineers? I have been in a couple of interviews to job applicants who couldn't bother less to fix typos and grammar in the first sentence of their CVs. The mere fact that we bothered to interview those candidates is disturbing.
There are literally people who say "I hate verbal/writing stuff, I'll become an engineer instead" during their undergraduate education, little knowing that at least in industry these skills are critical.
Popular opinion almost makes it seem like "writing well" (for human consumption) is almost the opposite of "writing good code" (for computers).
To be regarded as a great programmer, you need to know all the arcane details of a system, where those are the intricacies of a particular language or framework, or the small details of how a computer system works. It's the minutiae that counts.
With writing for humans, you need to have a very high level overview of things. You need to speak broadly and appeal to a common human understanding. The top level understanding is what matters.
Coding interviews reflect the change the industry is sensing and what this author puts well: the worst coding interviews are where they ask you about some small detail of a language or algorithm. It's a gotcha test. The better interviews ask you to show how you holistically approach a problem.
I disagree -- there are many situations in which your writing must display both a very detailed understanding of a system, AND a very detailed understanding of your audience.
And, similarly, you can code perfectly functional code that properly handles all the minutiae but is totally inconsistent with the general structure or style of the project and that is bad. The high-level considerations are still important there.
Agreed! The intersection of coding and communicating is really interesting. That is my personal bar for a really phenomenal programmer — someone who can produce code that communicates ideally to both humans and computers.
And this gets harder and harder depending on the task! It’s really tricky stuff.
Have you ever worked with a rockstar programmer whose code is unintelligible? Have you ever read something from a popular writer that was so wrong on a technical level? I wouldn't call either of those great.
Also I'm not sure how useful it is to test people on remembering minutiae of a system on the fly. How often are you correct about small details of a system you work with on a daily basis on the first try?
Basically, here is what I tell myself when I'm going to write something for an audience:
• Nobody gives a fuck ABOUT ME or how cool or awesome I am.
• People only care about how awesome THEY ARE.
• I am competing for their very short attention-span. Facebook, Netflix, and porn are my competition. This better be pretty compelling if they are not going to immediately hit their back button.
• I either need to address some real PAIN they have, or be pretty amazing at entertaining them. In most cases, addressing a real pain is easier. It's much harder to entertain better than porn, breaking news stories, etc.
• Structure for pain is clear:
1. Identify the pain and show how much it hurts and costs them
2. Show them the solution, and how good it will feel to stop losing and start winning
3. Anticipate and address their concerns. Are they worried about cost? Are they worried about how much work it will require? Are they worried what their boss or customers will think? Etc. Think of the most likely concerns or objections they will have and explain how to resolve them. All or most of their questions should be answered so that there is nothing in the way for the next step...
4. Call them to action to do something. Use your tool. Change a behavior. Etc.
The structure can vary a bit, but this is generally the structure. In a purely technical article, you may have very short sections on the pain, then spend most of the time on the solution. If the purpose is more for sales, then you'll want to have it more balanced and focus a lot on resolving concerns.
The article should be clear enough and structured enough so that every paragraph can have a headline. And a reader should be able to scan the headlines and know very quickly and clearly without having to think "what is this article about?"
If the article feels or looks like work to read, they will give up right away and you've lost them. There has to be something really compelling for them. How will this make them more awesome? They don't give a fuck about anything else.
They are milliseconds away from hitting their back button or searching for "nude guitar solos", so put the effort in to deliver something compelling and valuable. One well-thought-out clear useful article is far greater than a hundred jumble-thought aimless ones.
> It is with a larger organisation that writing becomes important for messages to reach a wider group of people.
I'm not able to fully agree. An engineer is more likely to write text that reaches a customer in its original form in a tiny startup or consulting firm than in a big organization.
The larger the company, the more of a cog you are with specialized tasks. Writing? That's a documentation person; just give them a rough draft capturing all the info. Customers typically talk to customer support, not to you. Customer support people have to write well, to be sure.
If the engineer started in a small organization which grew, but that engineer's responsibilities grew in proportion also, then that is apples and oranges. You have to compare how much writing is required in comparable roles.
I think people appreciate this about other people, so if there's a place where it is undervalued, it's when people evaluate themselves and their opportunities for improvement.
I remember Bjarne Stroustrup saying that an important sign that a person could become a good programmer was that they could write clearly in their native (natural) language. I can't find that quote, but I did find a 2013 interview [1] in which, forced to pick three key pieces of advice for budding programmers in their early twenties, his #2 was, "Learn to communicate well, verbally and in writing."
This article pitches the idea that writing is an important skill to advance your career. It makes the point that you will be better at spreading an idea and influencing people.
I agree with this, but to me personally, the more compelling reason to improve your writing is that will improve your work (not necessarily your career).
It is more about better communication than influencing people. I want people to more easily and reliably understand what I am trying to communicate. Understand my ideas, my doubts, my suggestions, my attitude, my feelings.
My writing was definitely valuable in my transition to software development two years ago.
Why is it undervalued? because you decided it's so?
It's extremely valued, and even specified as a requirement for most positions (either explicitly or under "communication skills").
It's undervalued if you observe the amount of deliberate effort most engineers put into improving that skill compared to the benefits they would garner from doing so.
I think writing doesn't get anywhere near the attention ot should be getting.I've met and I work with some really great people but boy oh boy they struggle to write.I'm not talking about producing the next bestseller but simply communicating simple ideas. I read what some of them write I think: wtf...if you were only able to write better you could be reaching the sky.. Technical capabilities+ ability to communicate well in writing is a killer skill and can literally elevate people to a whole new level..
Fully agree and I'd expand the point to cover communication in general. Explaining ideas clearly with text or voice is one of the characteristics that I've noticed in high-functioning engineering teams.
I did a talk[1] a few years back about my experiences helping a team to improve their communication skills. What surprised me was the emotional complications that prevent people from communicating effectively.
Is there are tutorials or training material you would recommend.
I have been hearing "plain writing" more and more...but not sure if it is the right thing.
I say it all the time: a significant fraction of my job is to read and write google documents. I’m either writing docs or I’m reading/commenting on docs someone else wrote.
Reading and writing are foundational skills needed in virtually every field. Especially especially especially at google.
Funny, I never thought that that would be the hill one of my plans would die on. Writing well - and reasonably quick - is rare, when you take the intersection of people that have that skill with people that are technically inclined the resulting set is super small.
Did anyone else find this article to consist of ironically poor writing? The blog post contains of a lot of fragments, run-on-sentences, unnecessary pauses, mixed tenses, dangling clauses, use of the passive voices, and no Oxford comma!
I'm surprised this is so far down. I'm assuming most people commenting didn't actually read it and are just agreeing with the sentiment.
Perhaps the author is not a native language speaker? That being said, I'm not sure why you'd write an article about the importance of writing if your writing is... below average at best.
Yes, the article was mediocre writing at best. The author made his point clear, so he achieved the core goal of technical writing, but the writing itself was clumsy and distracted from his message.
There are kinda two disciplines here, writing something that tries to convey a complex concept is important, but it's also important to be able to tersely describe a problem, and use correct, agreed upon language to do it.
Compare:
Wrong error message shows on Xm-z pages username input.
I would argue that having agreed upon naming, and explicit syntax for how to describe issues/improvements in-between your team members is almost more important than being a good writer. The bottom sentence isn't even grammatically correct.
As an engineer and now an author of a technical book I definitely agree with this. I have seen many places where they have a talented engineering team that cannot communicate what they have created etc. to everybody else. The worse anti-pattern is when they hire technical writers with no knowledge of the domain (or dev skills) to create documentation on how to use API's targeted at developers... The end documentation from that effort, unsurprisingly, is often borderline incomprehensible.
In fairness, the author is not a native English speaker. And he makes his point with clarity and cohesion. There are some awkward phrases, but by engineering standards his writing is perfectly fine :D
I started it because I found that being able to write effectively was my biggest advantage at work. Compared to others who were at least as technically competent as myself, I was more often able to persuade others to take the course of action I prefer.
I think writing well is a skill that is in very short supply all around, even in writing-focused areas like journalism. A major culprit in this, in my opinion, is how writing is taught in college. It's very common for students to be tasked with writing an essay with a minimum word count.
This has been training people into the habit of being unnecessarily wordy and obtuse.
What they should do, is give students a higher mark the less words they use to make their point.
You overestimate people's ability and enjoyment in reading concise writing that has each word measured carefully.
In order to pass an exam in university, I had to deliberately repeat myself in a few subtle ways, only to be commended how I managed to get my points across very concisely.
I find that writing well is somewhere in the middle: people are used to skip-reading, so being very concise is counter-productive: unless you want to repeatedly point them to actual bits of text that answer their question but which they probably went over as only fill-text.
So, I prefer to state my position concisely at the front, benefitting people like me who prefer it that way, and then expand it with examples and more elaborate arguments for those that need more.
Like this post: the whole point is in the first sentence. The rest is just for the majority who'd basically not even read it, let alone bother to understand it.
(As a consequence, I often miss the happy middle and become too elaborate: it's a struggle :))
In the US university system there are undergraduate requirements called distributional or general education requirements. The breadth of the courses cover humanities and arts, social sciences, and other classes under a Liberal Arts category. I wonder if there are similar requirements in other countries. Does an undergrad degree, say in India, have an apples-to-apples equivalent to an undergrad in the US with respect to the distributional requirement.
This is literally how I get “impossible” changes to happen virtually anywhere. There’s so much psychology that goes into the impact of the written word.
Writing well? I've had to read engineering drawings for QC in a precision engineering shop working with critical industries. Screw grammar and style being undervalued. You get told to fuck off if you complain about spelling.
edit - there is a pathological aversion to updating a drawing, not because of the work, but because of the process. People will do almost anything to avoid having to get an update signed off.
I think a lot of people doing the drawings are either dyslexic, or maybe just do not care. Also, engineering companies don't tend to have proofreaders. I can proofread, but learned quickly that I should not bother proofreading the drawings that came through. All it ever achieved was a torrent of abuse, combined with a flat refusal to even think about getting a new drawing issued.
This falls into the category of a much wider undervalued engineering skill -- communicating well. The best engineers tend to be excellent communicators. There is a whole group of extremely talented programmers who just don't understand why they aren't getting ahead, and nine times out of ten the answer is that they suck at communicating.
I recall my technical writing class in collage was actually pretty good and it was a required course. But when i went into industry there was not monetary connection to writing quality. Sometimes it is even better for developers to have convoluted documentation because then they make themselves indispensable to maintenance in the future.
I too took a technical writing class in college and it was very helpful.
I used to be a pretty good technical writer early in my career. Everything I did was documented throughly. Anyone could read my documentation and pick up the project.
Then we had a management change. I would literally get yelled at by my director because I was wasting time creating documentation. So I stopped. Didn't document shit, and the yelling stopped.
I'm at a new job now, and I'm trying to get back in the habit of documenting everything. Though those skills are very rusty.
I recently had a colleague recommend Writing for Computer Science[0]. It feels targeted more toward academics, but there's plenty of useful things in there.
Another undervalued skill is speaking well. Since joining Toastmasters my career has undergone a step change. Managers perceive me as being much more effective, even though my writing and coding skills have only continued growing incrementally. It's the best investment of time I've ever made.
I sometimes think that programmers come in two types: mathematically inclined or linguistically inclined. Think sorting vs parsing.
I only realized this after testing out of and skipping all English and writing requirements easily, but having to retake several mathematics courses during my time in engineering school.
In the Middle Age we needed to thumb through huge binders located in a room close to the mainframe. Tedious.
Then we could buy the books. We still needed to thumb through and it took time.
The the wastage of engineering hours was decreased by putting the writing to low level engineers. That was a good idea as it saved money.
That idea could be made even better by having documentation moved to another location by even lower paid staff. Great financial results!
In the meanwhile we got patterns and realized that all software is created the same. Documentation can be recycled and continuous releasing saves time for unneeded reviews.
Software and its documentation is really just assembling blocks. Learning from the leader in that space, Ikea's manuals yielded even greater results. And with additional ingenuity video was introduced. Saves trees, Ikea could learn from us.
These days one does not need to read much anymore, just google a video. And if a problem can't be solved, then agility comes to rescue. Lean development means problems are solved when needed and that is what agile users are for.
At USC, they had multiple mandatory writing classes and I felt that the people who did well in those classes did well in engineering too. I think there is a high correlation between being able to clearly write something down and explain it and understanding the concepts.
This article comes at a perfect time. As I want to work on my writing skills. I’ve found many recommendations in this thread on how to improve your skills but nothing focusing on technical writing.
Any recommendations for materials specifically for developers?
Ugh, I don't understand why people keep recommend the Pinker book about writing well. Pinker has the most formal god awful style I could imagine. There are so many better writers to learn from. Don't fall for mimetics guys.
I am from India and here writing skill for engineers is not valued at all. As someone into research, I found it important when I started sending papers. Academia here is not giving importance to the writing of its students.
The ability to be "agile" with writing is pretty important to some. I sometimes find I'll edit and revise (and tweak) a gamedev stack post many, many times over just little things.
> I have noticed a few skills that people often underestimate the importance of developing. Skills that add a significant boost to the impact of any developer. One of these ones is writing.
One thing I love to do is send any major communication I've written through text to speech. I've caught soo many mistakes that Grammarly or Word didn't when I hear it.
I agree that writing well is extremely important. However people like to do so much verbally in meetings, that what you write will probably not be read carefully.
Reading is undervalued, and just writing better won't fix it.
Good readers tend to underestimate this problem obviously. If you read the article I bet your colleague didn't, and he or she isn't interested in reading your better-catchy-succinct-effective-if-not-superlative writing either, and he or she is going to rewrite the system.
(Oh but exceptions I can think of are Harry Potter, and also the LKML as a vehicle for developing linux)
> Writing is only a way to convey information, there a many other ways to do it, and there surely will be other ways.
It's the best way of conveying information, especially in a business setting. It's accessible, portable, can be as detailed and nuanced as needed, you can copy it, you can reference it later, you don't need a proprietary solution to use it. In fact, you don't even need a computer for it. All other methods of conveying information in a business setting that I can think of (face-to-face communication, video and audio conferences, Power Point presentations, chat apps, symbols, source code) don't meet all of the above criteria.
> The current system favors people who know how to write in English
Now this is discriminating and narrow-minded. Nothing stops a German company from writing well in German - if that's their main language.
I'm curious which system you think is more fair and objective.
> A language that may work for you may not work for others
This could be generalized as "a solution that may work for you may not work for others". And that's ok. An organization can have its own culture. A part of this culture might be writing well, but also agile, open floor plan, working remotely, or afternoon mimosas. It's ok to disagree with the culture of a particular company and not be a good fit. You are free to prefer companies that don't emphasize good writing skills - which I suspect are the majority.
Agreed, hugely undervalued and I would argue pretty rare. My formal grammar is pretty poor and I mainly operate on what sounds right, but nonetheless I am commonly shocked by the basic mistakes that are made by most people including very senior people - poor punctuation, ambiguities, misuse of apostrophes etc. I don't know if this says something about education in the UK? But the main message to me is - things other than writing matter when it comes to getting ahead. Why bother showing it off or improving when it will likely just get you labelled as (if you can believe this still happens in a business like tech - but it does) a geek.
I actually have found that if you are an engineer who displays well-rounded skills in multiple disciplines, like business acumen, communication, writing and conflict management, this causes managers and non-engineers around you to view you as a threat, and they will work harder to undermine you and try to box you into a “engineer only” label.
Above all, you won’t be rewarded for these other skills, despite how vital they are.
It has been this way at every job (7 companies now, ranging from huge & bureaucratic to medium & popular to super new start-up). Whether it has been at a major tech company or the latest & greatest start-up, people have universally acted this way everywhere, often while talking at length about how their company culture causes them to not act this way.
I don't think this and other so-called "soft" skills are undervalued by engineers themselves. A good writer/communicator brings immediate value to any engineering team and will be treated as such, usually. It's the pointy heads and the business side of the operation who don't value it, because it's not sexy. IT and software engineering are abstract to them, so when they don't see "hands on keyboards" (writing code), they think no work is being done.
Software engineering will remain in its infancy as a "profession" until software engineers themselves organize and better assert their own professional standards. Writing and iterating over documentation is an ISO standard that is ignored 99% of the time. If you ignore your professional standards, you are not a professional, no matter your title or your salary or even your field of work.
It definitely is undervalued. There is very direct evidence of this: technical writing plays exactly zero role in the hiring process. That process tends to be more than 90% or so focused on coding, and the other 10% is not writing, it is some combination of credentials, knowledge of current trends in the field, ability to seem like you would fit in at the company, and drawing system diagrams. But technical writing - in code documentation, design documents, task definitions, bug reports, emails, and chats - is often the greater portion of my job in a week, and it is pretty much always the more important part.
I agree a bit more that "empathy" is sometimes used in a BS-y way, but at its core it just means seeing things from more than only your own perspective. Which is definitely an important thing to do. I would probably agree that it is undervalued, though there seems to be more awareness or at least lip service to it than to the importance of writing.
It's definitely undervalued by engineers themselves. I.e., the majority don't seem to treat this skill as a priority in their professional development. However, it's definitely not undervalued by the companies that hire them. Especially as they progress through their careers, where they will experience a glass-ceiling affect if they have not sharpened that skill.
EDIT: Fixed stupid autocorrect error (thanks sokoloff). I wish browser inputs had grammar hints as well as spelling correction.
I think this is true inside a company, but it is another example of how weird our hiring techniques are. Writing plays basically no part in the hiring process. So for those engineers who have progressed by sharpening that skill, it is jarring to find that the barrier to their next job takes absolutely no account of it. You can spend years impacting or entirely setting the technical direction of a project or entire company through your writing (and verbal communication as well), and then find that all you're asked during your interview for your next job is to solve some made up problem using code on a whiteboard. It's bizarre.
Your comment made me realize that even when we hire execs/senior execs, I can't recall ever specifically evaluating their writing skills. I only recall doing so for dedicated comms people, but it's just as relevant for execs and yet we don't seem to do it there either.
Though I was a "pretty good or better" software engineer, it's almost surely the case that I've made more career gains from English-language writing than code-writing during my career.
(Normally I'd let this pass without comment, but because of the specific topic of this comment chain, you mean "glass-ceiling effect" not "affect" there.)
This is such a weird take. Your own comment here is an example of writing for humans that uses emotional language to try to persuade an audience. By writing this comment at all, you imply that your comment is wrong.
Writing well may not be undervalued from a managerial standpoint, but I think many individual engineers undervalue developing good writing skills. That assessment is based on personal & anecdotal experience. Writing skills are a subset of communication skills. Communication is largely "getting the idea(s) in my head into your head with as little ambiguity and confusion as possible". Once a team is is reasonably large and diverse, this becomes very valuable and important to the individual engineer.
David Perell (host of the North Star Podcast) has been tweeting a lot of good things about the value of writing + writing tips:
- https://twitter.com/david_perell/status/1127348174404890625
- https://twitter.com/david_perell/status/1124002449646395392
- https://twitter.com/david_perell/status/1116485842615377921