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.
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.)
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.
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.
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.
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.
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 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.
>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 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.
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.
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.
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'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!
> 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".
I disagree with you, but since I'm shadowbanned, there's no point in explaining why.
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).
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.
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.
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.
> 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.
>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.
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.
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.
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?
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.
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.
> 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…)
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?
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.
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.
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.
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.
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.
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.
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 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.
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).
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.
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.
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.
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.
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.
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.
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.
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
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.
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.
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 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.
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.
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.
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.
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).
Well, let's read each other charitably instead of doing this sort of thing, shall we? GP is not describing a binary choice but rather a set of priorities.
A lot of what is called "good writing" is really just a collection of signifiers that don't have anything to do with expressing ideas clearly or succinctly. There are plenty of people who would die before ever writing "y'all" but would gladly take 7 paragraphs just to get to the fucking point.
GP is describing a preference for clarity and succinctness over those signifiers.
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 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.
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.
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 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.
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)
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.
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.
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).
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.
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 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.
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.
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.
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.
- 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
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".
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.
#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.
"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."
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.
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.
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.
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.
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.
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.
> 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.
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.
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.
"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."
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."
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.
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 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?
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.
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.
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.
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.
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.
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 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.
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.
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.
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?
> 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/
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.
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.
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:
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 :))
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.
384 comments
[ 4.0 ms ] story [ 298 ms ] threadI feel like these are such softball answers, as no one will say no, this is bullshit.
EDIT: Fixed stupid autocorrect error (thanks sokoloff). I wish browser inputs had grammar hints as well as spelling correction.
(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.)
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.
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 mention this purely in the interest of pedantry.
I think the ideas are related.
It's layered on top of a quote of Guindon he uses in a book about TLA+ in order to make a point for using math to formally specify systems
The link has changed: http://www.petermichaud.com/essays/the-secret-about-writing-...
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.
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.
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.
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.
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.
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 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.
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.
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:
https://github.com/kstenerud/streamux/commits/master?after=7...
https://github.com/kstenerud/concise-encoding/commits/master...
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!
I disagree with you, but since I'm shadowbanned, there's no point in explaining why.
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.
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.
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?
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?
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.
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.
To me it seems that there could easily be confusion between these two interpretations.
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 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."
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.
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!
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.
Also it's basically "what that word means in English".
I don't think it takes that long to study.
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?
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.
> 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…)
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?
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.
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.
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.
the same could be said for using static types to express the thoughts and formal reasoning rather than english though.
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've yet to find anything that packs a bigger punch than screenshots annotated with MS paint paired with concise description.
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.
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.
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.
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.
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.
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.
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).
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.
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.
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?
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.
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.
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.
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 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.
And certainly, taking someone’s ability/inability to write as a general sign of their intelligence or empathy or level of talent is a mistake.
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.
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.
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.
Oh..wait..
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.
I have this very smart colleague who writes in long paragraphs and I always zone out somewhere in the middle.
It's a terrible way to figure out the essentials.
I much prefer PowerPoint diagrams that list the essentials over long paragraphs that include the gory details.
A lot of what is called "good writing" is really just a collection of signifiers that don't have anything to do with expressing ideas clearly or succinctly. There are plenty of people who would die before ever writing "y'all" but would gladly take 7 paragraphs just to get to the fucking point.
GP is describing a preference for clarity and succinctness over those signifiers.
This is a not a matter of "Never end a sentence on a preposition." "This is the type of errant pedantry up with which I will not put."
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 wrote a book (http://shop.oreilly.com/product/0636920043027.do) and it was the hardest thing I ever did.
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.
Still can't spell tho, and homonyms will be the death of me.
Why is that annoying? Its perfectly clear and concise. Good writing imo.
> 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.
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.
I personally wouldnt be happy doing that. I value intellectual honesty extremely highly for some reason.
Have you read this? I like it.
http://classics.mit.edu/Epictetus/epicench.html
Its an Enchiridion for Stoicism. Literally a handbook designed to be carried around and consulted as situations arise.
It seems some people just have a disconnect between text and verbal processing.
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 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.
My friend, who isn't good at interpersonal skills, is trying that.
Can this work for him ? or is the trust created via face-to-face is irreplaceable for convincing others ?
Of course, you have to get decision makers to read it...
tl;dw : you have been taught to write to people(teachers) who are paid to care about your writing.
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)
https://www.amazon.com/Elements-Style-Fourth-William-Strunk/...
There is a great episode of Lexicon Valley where the dustier advice from The Elements of Style is called out: https://podcasts.apple.com/ca/podcast/against-strunk-white/i...
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.
I bought To Sell is Human, thank you for that one.
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.
True, unfortunately it’s also the majority of sales.
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.
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.
Edit: Upon re-reading the thread, I may have misinterpreted your original point. Disregard my comments.. sorry
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.
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.
Measure twice, cut once. Take the time to write carefully up front and proofread, before you submit it to a lengthy process.
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.
The main value of it felt that enshrining factual objective information and basing all discussion around that.
Any info on what the writing class covers ?
- 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
[0] https://www.amazon.co.uk/Pyramid-Principle-Logic-Writing-Thi...
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".
[1]: https://www.amazon.com/Elements-Style-Fourth-William-Strunk/...
[2]: https://www.amazon.com/Writing-Well-Classic-Guide-Nonfiction...
This is something I struggle with so I took your advice and found this:
https://www.grammarly.com/blog/a-scary-easy-way-to-help-you-...
Thanks!
[1]: https://smile.amazon.com/Style-Clarity-Chicago-Writing-Publi...
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.
[1] https://languagelog.ldc.upenn.edu/nll/?p=15509 [2] http://itre.cis.upenn.edu/~myl/languagelog/archives/003366.h...
https://youtu.be/suAASPc_s0A
Article: https://www.geekwire.com/2017/prepared-6-page-memo-geekwire-...
6-Pager Example: https://cdn.geekwire.com/wp-content/uploads/2017/10/Jeff-Wil...
Guidelines: https://blog.usejournal.com/writing-docs-at-amazon-e02580861...
Previous HN Discussion: https://news.ycombinator.com/item?id=19115686
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.
Also sounds like the Chair did not control the meeting.
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.
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.
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.
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.
If somebody really needs my time, they can tell me why -- or go through my manager which they should be doing anyways.
It wasn't in my situation, mostly because everyone sucked at meetings at an astounding level. But I'm not there anymore thankfully!
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.
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.
Who does this 1-page explainer go to ? who is the gate-keeper ?
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.
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.
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.
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.
[1] https://vimeo.com/134601419
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.
(1) https://slab.com/blog/jeff-bezos-writing-management-strategy...
(2) https://en.wikipedia.org/wiki/Gunning_fog_index
https://www.amazon.com/Writing-Works-Communicate-Effectively...
[0] https://www.springer.com/us/book/9781447166382
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.
What a way to waste time of your audience.
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.
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.
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.
This sounds like a good piece of advice to keep in mind. It's nicer for the reader to not have to wait till the end to get what's going on.
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…
[0] https://hbr.org/2016/11/how-to-write-email-with-military-pre...
"If you started out trying to read this, but then realized it was too long and just skipped to the end, here is what you missed."
> The goal was bla bla... We tried X... That showed Y. We tried Z, which sort of worked. At the end, we modified Z to work, achieving ABC.
should just be
> We achieved ABC toward our bla bla goal using a modified Z. [supporting lines]
- https://opensourcesurvey.org/2017/
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:
https://github.com/franciscop/ola/
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 :))
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.