I was a doc reviewer in my corporate past life and found myself using many of these guidelines. I’d add one more: don’t use different names for the same thing. Many of the docs I reviewed had multiple authors and quite often they used slightly different terminology. This really complicated things for readers. I eventually realised there was a meta-principle here: in tech writing, the reader should never have to resolve ambiguity created by the authors.
One of my pet peeves while reading technical documents is coming across acronyms that have not been introduced to the reader yet. When this happens over and over again across several documents of a project and people working on the project change over years, sometimes we end up in a situation where nobody can tell anymore what a particular acronym expands to.
In fact, more than once, I have seen the bizarre situation where a team is responsible for developing and maintaining some service known by the name, say, ABC, but nobody in the team knows what ABC really expands to. In such instances, in order to avoid choosing a new name and updating all related documentation etc., the only recourse is to treat ABC as a proper noun and move on.
Fictitious example: To obtain an access token for CDIS, first go to DMC at <https://dsc.prod.example.com>, click on the entry for "CDIS" on the left sidebar, click "Generate Access Token", and copy the token.
What I would like to read instead: To obtain an access token for Customer Data Indexing Service (CDIS), first go to Data Management Console (DMC) at <https://dsc.prod.example.com>, click on the entry for "CDIS" on the left sidebar, click "Generate Access Token", and copy the token.
A glossary is the most important document ANY project should have and maintain. Everything else is secondary.
Nah, it doesn't pass the sniff test.
Is it more important than a list of critical bugs?
A document explaining how a developer can get the application up and running?
A document detailing how the production server is setup and how to gain access?
When you think about it, lots and lots of projects manage without any kind of glossary but would go up in flames without some kinds of documents.
Perhaps in terms of the importance to effort ratio. How long does it really take to maintain an adequate glossary?
I find glossaries quite often not very useful because they tend to get copy/pasted across documents and the acronyms are often just expanded without giving the correct meaning in the context of that document. I'd rather have it fully spelled at first usage, with the acronym in brackets. This enforces a more natural order of writing and reading the document and provides a better context.
Agree strongly. I think an even more insidious version of the parent comment is when common nouns that have specific meaning in a given context are used as such, without it being explicitly called out.
Agree. A glossary is a way to introduce a domain piecemeal, without a long-form explanation.
Please explain what ANY expands to...
I think the google guide to technical writing recommends to write out acronyms once per chapter/section.
Should always be on first use, of course.
I see this happen in non-technical spaces too... product managers using project-specific acronyms and codenames in front of an audience of new people. I can't tell if it's some form of narcissistic gatekeeping, or just lack of mindfulness and deep entrenchment in the project for too long. I am so hyper conscious of this that I will stop meetings to ask the presenter to define the terms.
HTML has an entire tag for this. There is no good reason not to define those every time they appear.
I'm always tempted to go passive-aggressive and misinterpret the acronym. I don't, but I'm tempted to.
E.g. "Couldn't we simply write an email to the Computer, Data, and Information Services department for the access token? This keeps a paper trail, and explains why you need Digital Media Credentials in the first place."
I'm someone who's jumped from Medicine to CompSci. Each field uses their own obscure acronyms that highly intersect. I'll spare you the embarrassment that comes from someone making a "Pro Rectum" request.
What I would like to read instead: To obtain an access token for Customer Data Indexing Service (CDIS), first go to Data Management Console (DMC) at <https://dsc.prod.example.com>, click on the entry for "CDIS" on the left sidebar, click "Generate Access Token", and copy the token.
Even better:
<a href="https://dsc.prod.ex.com/gettoken">Get</> an access token from the Data Management Console (DMC) to access the Customer Data Indexing Service (CDIS).
The best documentation is no documentation. This documentation is there because the two systems aren't linked and that is the real issue. If there isn't budget to do the integration, then better is have the hyperlink to DMC on the log in page of the CDIS, which can then avoid the separate documentation altogether.
This is a related to my number one problem with technical writing or text books: forward references.
"Let's talk all about a topic we will define three chapters from now"
Learning about things with undefined terms, concepts and acronyms is much harder and may require multiple passes over the material.
It's a hard part of writing a linear book about a topic that's probably a graph, but good writers manage it. Bad writers just leave their readers confused.
I love this.
Inevitably I want to make some improvements.
“He laughed with the kind of booming abandon that made the whole restaurant turn around and look.”
The kind of? If it's a kind that exists generically then we can't have a past tense, so:
“He laughed with the kind of booming abandon that *makes* the whole restaurant turn around and look.”
But really, why emphasise it being generic? This is better:
“He laughed with *a* booming abandon that made the whole restaurant turn around and look.”
---
Use lists where relevant, because it’s easier to read a bulleted list of items than to read a paragraph with the same information.
Use lists only where all the items have the same status, in some sense. An ordinary paragraph can't be broken up into bullet points.
If it's a kind that existed generally, then we can have a past tense.
"He laughed with the kind of booming abandon that made the whole restaurant turn around and look, in the before-times."
We now live in a sad, post-apocalyptic world, with no booming, no abandon, no turning around, and very few people in restaurants.
This is hardly a bad description of the current state of affairs.
We can describe "a kind that exists generally" even if the restaurant turned and looked (then) and would still turn (now and in the future).
Just need to change "the" with "a":
He laughed with the kind of booming abandon that made the whole restaurant turn around and look.
to:
He laughed with a kind of booming abandon that made the whole restaurant turn around and look.
In this case his laugh is still described as having a generalized "booming abandon", but the reaction of the patrons isn't a necessary reaction to that "kind of" laughter, but to that particular instance of it.
That is, the noun is "the kind of booming abandon" and not "the kind of booming abandon that made the whole restaurant turn around and look".
This is the best version.
“He laughed with a booming abandon that made the whole restaurant turn around and look.”
Don't the people in the restaurant actually turn around in this sentence, whereas they didn't in the original, because it's just describing a kind of loudness with an example?
“He laughed with the kind of booming abandon that makes the whole restaurant turn around and look.”
Well, yes, but one is telling and one is showing. A good story teller shows and not tells.
That's just a literary superstition, similar to absolutes we tell kids such as "you should never lie" (that in real life are never that clear cut).
A good story teller can both show and tell, depending on whatever fits the story, their stylistic choice, and their intention.
Don't the people in the restaurant actually turn around in this sentence, whereas they didn't in the original
No, the original said "made", so I think they actually turned around.
It feels like your change is changing the scene? The author's sentence makes it seem like the laughter was not in the restaurant, while yours makes it seem like it's taking place in the restaurant. Maybe I am overthinking it!
The kind of? If it's a kind that exists generically then we can't have a past tense
It still applies if the past tense is only meant to apply to the reaction to what he did at that point in the past ("made the whole restaurant turn around and look") and not to the general reaction to such booming abandon.
Then this:
“He laughed with the kind of booming abandon that made the whole restaurant turn around and look.”
Can still refer to the generalized abandon, but should rather be:
“He laughed with a kind of booming abandon that made the whole restaurant turn around and look.”
Though, the non-generalized version is indeed better.
Maybe he often visited that restaurant and laughed with booming abandon and no longer does :) there was, over a specific period, a specific kind of booming abandon, justifying "the" - but there no longer is, justifying "made".
Any other engineers trying to improve their writing skills? Any additional resources or tips to help me refine my drafting and editing process?
Anything by Diana C. Reep. Technical Writing: Principles, Strategies, and Readings is particularly insightful:
Strunk & White is always good to thumb through: https://archive.org/details/TheElementsOfStyle4thEdition The Wikipedia has links to other copies, like on Project Gutenberg.
I can’t recommend Strunk and White’s Elements of Style enough.
Not a source, but rather an exercise: give yourself a tight word count and rework your essay until it fits. When one third of your article has to go, you start looking really deep into how to extract as much value as possible out of every word.
Google has a few courses about technical writing for engineers:
I've been trying to improve by making a conscious effort to practice it. I've been trying to blog and even wrote a book, partly to increase my writing skills.
The book that helped me the most is On Writing Well: The Classic Guide to Writing Nonfiction.
I also wrote a blog post about some of the lessons I learned:
https://www.jonashietala.se/blog/2023/11/25/writing_lessons_...
There are innumerable sources online for improving technical writing and they all generally repeat the same conventions and "rules". I tend to warn people, though, that over fixating on technical writing will not make you a great writer but just a capable technical writer.
If you're looking to improve your writing in general, then I think Joseph Williams' "Style: Towards Clarity and Grace" is the single best book on the subject written so far. Rather than simply state certain "rules", it methodically workshops examples to show how you can write and rewrite a sentence to change your meaning and emphasis at will.
Developing Quality Technical Information - https://www.amazon.com/Developing-Quality-Technical-Informat...
My review + some notes - https://river.me/blog/book-review-quality-technical-informat... (it's very good)
Death Sentence - The Decay of Public Language, by Don Watson.
Blisteringly good. Not aimed at technical writers, but encourages you to think about how to really use language effectively and robustly.
All great advice. Except for “avoid passive”.
It’s a part of the toolbox that changes the perspective on an action.
“The pull request got merged” vs. “The maintainer merged the pull request”.
If i want to talk about the new feature that gets implemented by the pull request, then I mislead the reader by emphasizing the maintainer, rather than the pull request.
The passive also allows you to choose whether you want to call out the source of an action.
“The pull request got merged by the maintainer.”
Yes, you can misuse it to fudge responsibility, but you don’t need the passive to do that.
"They merged the pull request" sounds fine to me.
As the parent notes though, "the passive also allows you to choose whether you want to call out the source of an action", while "they merged the pull request" does not.
That part, I do not get. Do they mean it permits a rewrite? But all sentences do.
They mean it allows you to not point out who did the merge.
If the PR introduced a BUG or was a bad choice to merge it, you might not want to use an active form, because then you have to say who did it (for example, in a report), to protect them, or to not appear like you're pointing fingers. The passive voice allows you to state the fact that the commit was merged, without mentioning anybody.
"John/Jil merged the pull request"
vs
"The pull request was merged" - you can chose whether you want to include "by John/Jil" or not.
In context, though, the passive version can sometimes make for smoother reading. My general rule of thumb is that each sentence should establish context at the beginning by referring to the preceding material and then introduce its new idea at the end— Whether it’s best to start with the maintainer or the pull request depends on which of those you’ve already been discussing. (I didn’t come up with this idea, but I unfortunately can’t remember where it came from)
Possibly from here?
* The Science of Scientific Writing (1990) by George Gopen and Judith Swan: https://web.archive.org/web/20240120063715/https://www.ameri...
They say:
In our experience, the misplacement of old and new information turns out to be the No. 1 problem in American professional writing today. […] Put in the topic position [the beginning of the sentence] the old information that links backward; put in the stress position [the end of the sentence] the new information you want the reader to emphasize.
It's a useful article, that I also mentioned in this answer: https://academia.stackexchange.com/questions/85286/why-do-re... — see also this video https://www.youtube.com/watch?v=jLPCdDp_LE0 of Judy Swan, one of the co-authors (the accompanying handout is https://web.archive.org/web/20170331212200/https://www.cmu.e...).
I was once caught in a contractual dispute that occurred because the author used passive. The contract basically said 'X will be done' without identifying whether the customer or contractor was expected to do X. Unfortunately this wasn't spotted until the contract was in place.
If you must use passive in situations like these, please at least identify the agent, e.g. "X will be done by Y". Oy just use the shorter, explicit alternative: " X will do Y"
Unfortunately this wasn't spotted until the contract was in place.
Sorry, couldn't resist pointing out this use of the passive voice.
ha!
In my defence I was demonstrating the way that passive voice can also be used to obscure responsibility after the event, as in "mistakes were made"
If I could add one prescription to TFA, it would be to avoid using "just" (the adverb, as in "simply") at all costs.
"A monad is just a monoid in the category of endofunctors."
Maybe it is, maybe it isn't, but none of that is simple. There's that math joke about proof methods, and this would be "proof by intimidation".
When describing a process: "To measure the inverse reactive current in unilateral phase detractors, just use an ordinary turbo encabulator". Why "just"? Are there other methods? For what reason is this the preferred one?
When giving advice: "Why don't you just use a bash script?" This implies your suggestion is simpler or more economical than my proposed approach, therefore better, but you aren't supporting its alleged superiority with arguments I can counter, only implying it.
monads, "just"
I think that line is usually quoting a popular joke from a comedic tour of various programming languages, and "just" is appropriate.
A monad is just a monoid in the category of endofunctors. What's the problem?
I see. It was the first sentence that came to mind. The point I'm trying to make is, in my experience, "just" is often abused, as it conveniently relieves one from providing a sound argument.
Totally agreed. Your other examples were spot-on, and the general sentiment also makes sense to me.
What is TFA?
What I meant by it is "the fine article", meaning the post. Actually using acronyms goes against "Don't assume knowledge", incidentally a point in Eva's list (the article).
I've learned the acronym here on HN, googled for a second and found "the fine article" as explanation, but now that you ask I've checked wiktionary... and apparently the commonly accepted meaning is derogatory (the f*king article, like "RTFM", "read the F-ing manual).
Lesson learned, won't be saying "TFA" again unless I mean f-ing
Yes, good suggestion. I've also stopped using "just" when speaking or writing in the last few years. You can almost always drop it and retain the same meaning without sounding rude or dismissive.
I've noticed this in at least one other language I'm loosely familiar with (Bulgarian) and it holds there too. When the speaker adds "просто" it has the same effect of sounding rude and dismissive.
Right: rude, dismissive, patronizing. Gives me exactly this impression, you put it into words better than me.
Hello everyone! This is my post! I'm flattered and honored that it resonated with many of you. Since I wrote that post, I followed my curiosity to become a software engineer myself. After doing that work for a few years, I've found myself missing working in a more writing-heavy role. If you're looking for an excellent technical writer, developer advocate, or another role that blends communication expertise and technical skills, let me know! You can contact me through the form on my website (https://evaparish.com/contact) or via LinkedIn.
I really got a lot out of the article. I think it will help my write more succinctly and clearly and to be better understood.
One question: after writing the sentence “I really got a lot out of the article.”, I wondered: is this extraneous? Is this clear? Am I saying precisely what I mean? And I think, yes, I meant exactly what I said, and I went into detail in the following sentence. I am just curious what you think.
I am not the author, and am sharing feedback because you asked with honest curiosity.
Your writing is not clear to me. Using the word “really” is extraneous. Using “I think” is also extraneous; I assumed these are your thoughts.
As the author notes, replace “it” with “the article”, or better yet a specific quote or idea distilled from the article.
Helped “my write” should be helped “me write”. You use two -ly adverbs, which could be avoided by restructuring the sentence.
You also have a list of two (succinct and clear) and then a single item (better understood). Consider breaking these two thoughts into separate sentences.
I really (err, vehemently) disagree with this feedback.
Your writing is not clear to me. Using the word “really” is extraneous.
What's not clear? He said the article helped him, it seems pretty clear to me. The "really" was for emphasis, which is fine.
Using “I think” is also extraneous; I assumed these are your thoughts.
"I think" indicates the degree of certainty. The author is uncertain but deems it likely.
As the author notes, replace “it” with “the article”, or better yet a specific quote or idea distilled from the article.
The previous sentence says "the article", and the next one says "it" to avoid repetition. Saying "the article" twice would be awkward.
Very odd feedback, given how obviously out of place the corrected sentence would look.
Your first paragraph is clear, indeed the first sentence is the gist, the second explains it in more detail. The second paragraph -- the question and own answer -- seems a bit superfluous to me.
You using HTTP in the example without explaining it, was really funny. Was that joke on purpose?
You’ve heard this advice before. But you should understand why you shouldn’t use passive voice in your writing. It’s not just “bad style.”
The ususal misunderstanding that everyone repeats.
Read Williams‘, Clarity and Grace, or watch McEnerny‘s lecture on YouTube.
Passive has its use, and it‘s not "to obscure who is doing the bad thing".
Thanks for the references. I'll check them. I'm extremely biased against the business use of passive voice, to the point of getting so worked up when someone does it with me on mail or slack, that I need go to a quite room and relax for 5 minutes.
The purchase order has been made.
Your virtual machine has been created.
I see this a lot in corporate environments, and it's by low level managers thinking every bit of information they're trusted with is so delicate and confidential, they must go above and beyond to reveal the least possible amount of it. Note, in the examples above, it was the manager themselves doing the action. What's wrong with "I did this", "I did that"? This is LARPing as CIA agents (or whatever), and they like the sound of it (I want you to know I have information I can't share, you little shit!).
"I've just created your virtual machine" peasant
"Your virtual machine has been created" special ops elite force management
Mind you, 99.999% of the time, the concealment of "who did the thing" is totally unnecessary. It's only there to reinforce status.
The opposite:
"I've just created your virtual machine" - 3 year old, "mummy, mummy, /I/ did this! praise ME!". Got to insert yourself as the first thing in the sentence, as if the customer cares who did it.
"Your virtual machine is ready" - Waiter, assistant, comfortable out of the limelight to let the focus be on the customer and what they are interested in.
"I've just created your virtual machine" - You didn't make the deployment pipeline, you didn't build the hosting, or write any of the hypervisor or guest OS, you ran one script and now you're taking all the credit. Embarrassing.
Good point. Focus on the customer. Didn't see that aspect.
Indeed. However, it is the most oft-repeated consequence of using Passive voice. In general, I use active voice and when it makes sense, passive voice is used as well.
Williams’ book is really excellent. It deserves to be more widely read.
One of the best writing tips I've ever gotten was to avoid using demonstrative pronouns. Instead of saying “this” or “that,” you should add a noun to spell out exactly what you’re referring to, even if you’ve just mentioned it.
This piece of advice is maybe the only thing I remember from my college English class. A naked "this" or "that" now feels shamefully lazy to me.
Totally agree! The worst example is a paragraph that starts with ‘this’. The author might remember what ‘this’ means at the time of writing, but other readers have to then insert themselves into the author’s stream of consciousness. ‘This’ paragraphs also make no sense when extracted from the main report, or to readers who are dipping in and out
'This' paragraphs are fragile to editing. Ensuring that your text is robust to updates (e.g. insertion of an extra paragraph) is good practice.
This is good advice.
“This piece of advice”, I guess it’s good advice just don’t overdo it?
Original source found at:
Some HN folks here are so thin skinned that they down vote a reference to Strunk and White?
Was your comment (“Original source found at…”) intended to be a reply to some other comment, rather than being a top-level comment? Or did you actually mean to suggest that the original source of the post here (“What I think about when I edit (2019)”) is Strunk and White? The latter seems pretty misleading and inappropriate.
It's definitely nothing new but good advice bears repeating over the decades :)
For big picture stuff on writing I also like "On Writing Well" by William Zissner and "First You Write A Sentence" by Joe Moran (which is a bit more British).
Is there a service for this? (Standard developer question).
I found myself writing a book recently, completely left field to my normal technical work. I'm intending on approaching a literary agent but I need it reviewed first and I'm looking for dispassionate, distanced, but informed opinions.
completely left field to my normal technical work.
I'm assuming this is another baseball reference. As a non-American: what does it mean? :)
Well, a copy editor maybe? https://en.wikipedia.org/wiki/Copy_editing
I've never used one, but I assume there are professionals for hire to do this.
In fact I've read one of the advantage of going with a publisher (as opposed to self-publishing) is they give you an editor. But again, I'd expect a freelance market to exist.
Who are you writing for?
This is the hardest part of writing for me, especially blog posts.
I can never decide if I'm writing for a) highly technical readers who know 95% of the concepts my idea is based on, and I just want to connect the concepts together in a way the they might not have thought of, b) generally technical readers who have a grasp of the concepts my idea is based on, but will need some details to tie them into the idea I'm building on top, or c) readers who are not-especially-technical in the field, who might be nevertheless be interested in how a few things works, and my idea too.
I feel like part of it is that I am all these readers, depending on the subject. I enjoy reading articles about the areas of software dev I'm deeply interested in, but also about the odd idiosyncrasies of software that is used in fields I don't normally cover, but I also enjoy reading articles about e.g. the challenges involved in developing geothermal drilling systems, or elevator systems in 80+ story buildings, despite having very little experience in either.
I keep going through cycles of "If I just explain this part in a bit more detail, the post will be accessible to an order of magnitude more readers" to "this is way too long, I should cut some explanations, or add footnotes, or more wikipedia links" to "I'm assuming way too much previous knowledge here, or asking the reader to do too much extra work to follow my point".
Yeah, I find picking the audience difficult too. For my blog posts, I want to include the details for specialized readers, but also make the post accessible to the generally technical readers (roughly the HN crowd). (If I wanted to write for only the first group, I'd write academic papers.)
My solutions are to add enough background for someone who isn't an expert (even if it seems repetitive), and to use extensive footnotes for information that most people won't care about. Also, I try to put topics into a broader framework: a few paragraphs on history and why the topic is important. A narrative framework helps too, so even if someone doesn't follow all the details, they get a sense of going on a path e.g. from problem to solution. I also try to break up massive chunks of text with photos or diagrams but worry that I lean on this too heavily.
When I read popular books on scientific topics, I try to study the techniques that they use. For example, "An immense world" is crammed full of interesting facts and stories, keeping the book even though it is discussing technical concepts of sensory perception. "Immune" describes the immune system in detail, making heavy use of metaphors and imagery and repeating these throughout the book. Other books focus on the people, moving the technical details into the background.
I'm no expert on this, of course. People seem to like my blog posts, though, so I figured I'd share my thoughts.
Good question, and one I'd like to see discussed more too. From my point of you, your point "a)" is the one I never choose. In my opinion, one could rarely write something for that audience which might be novel to them. Perhaps I'm just not that smart, but to me, when I picture the true masters in my field, I rarely need to communicate anything to them that they haven't figured out for themselves already, and in the rare case that I might, those types of people don't mind a bit of revisiting of the fundamentals anyway.
My favourite type of writing is one that also comes in handy to myself a couple of years down the line, which inevitably involves a modicum of handholding and starting from some fundamentals. So I'd say most of the articles should be b) or c).
Don’t use adverbs
Indeed!
Back around 20 years ago I was with an MSP. We depended heavily on having a well written - as current as possible - prod guide for all operations.
At some point it occurred to me that there was likely a way to draw upon the experiences of those who came before us. In my case, it seemed fitting to use newspapers as a reference.
Somewhere I’d come across a concise guideline, a list of do’s and don’ts. The only thing I clearly recall now is keeping the key info “above the fold”, which is likely something that might puzzle someone who has never handled a newspaper. Even so, the concept is easy to share and grasp.
I wish I’d kept that list. I’ve tried looking for it within the past couple years, to no avail.
What is an MSP?
My brain must be warped by using LLMs because I could not help but think that it would be an amazing prompt, complete with multiple examples of each principal. Perhaps good prompting is good writing?
I thought the same.
(I did something similar in drawing. So it's a not uncommon path)
Get your art sharp. Digest that into a science. Digest the science into automation.
(And yes, one could argue that the result is a crystalline turd.)
I needed the repetition tip the most.
I always feel like repeating myself makes the text unwieldy and then clutter it with "this".
Grammarly always complains, "What is this refering to?"
Well, obviously a concept of the previous sentence!
I will repeat myself more often and then rephrase the repetition.
Honestly, I would recommend never using "this" or "that" - it often makes sense only after you force the reader to re-read the sentence.
Whitespace is key for technical documentation but can also be used to great effect in blog posts, emails, and elsewhere. It’s hard for people to read long paragraphs, especially on a computer screen. They will zone out.
100%. The explanation (?) I first heard which helped me 'get' this whitespace principle was along the lines of
Have you reached a page in a book with no paragraph breaks and thought 'oh no'?
You know, I kind of feel this way about code too. Sometimes people don’t put in a lot of blank lines to break things up and I find that a little harder to read and a bit more intimidating than reading with a few blank lines between concepts/actions. In fact, I was thinking after I read the article, maybe many of these principles apply to writing maintainable code too.
I've heard English teachers cargo cult the passive voice thing for ever.
This crowd will understand the passive voice as a form of abstraction. If anything could suffice as the subject, then it's not important to the meaning of the sentence, and you convey that in English by implying but not specifying the subject (the passive voice).
In scientific procedures for example, the whole point is that anyone could replicate it. 30 grams of goop was added to the beaker. Doesn't matter if it was you or one of your coworkers, or another group trying to replicate.
When I learned about passive voice, scientific writing was often mentioned as an explicit exception. What you say makes sense when you are abstractly describing something that happened, but also I'd argue that "We added 30 grams of goop to the beaker" or "Added 30 grams of goop to the beaker" is clearer than "30 grams of goop was added to the beaker". Depends on the context and style conventions of course, but often passive voice is still poor/indirect writing in many scientific contexts.
I would add eliminating future tense. There's very few times when future tense is actually required. It's one of my pet peeves when docs say something like "Click X. This will open a prompt ..." when it can say "Click x. This opens a prompt ..."
Yes. The user is living (i.e. working) in the moment, and so should your text.
All in all I think it is a good and well written guide.
I’d like to add support for using passive voice in work / business emails. This is great, not only for obscuring blame, but obscuring the _opportunity_ for blame.
You might think it’s obvious what an acronym means, but a new reader may not.
The other scenario is when the reader is not new, but it is too late to ask.
This is smart stuff. All of it makes good sense. I speak as a compulsive editor.
You can tighten it up, and tighten it up again, and sloppy doggerel becomes so clear.
Really a lovely piece of writing about writing.
Eva is a fellow technical writer. I'm glad to see tech writers get visibility in here.
Thank you for the write-up!
I did not know I have been erroneously omitting commas in English. In Slovenian, my native language, commas always delimit clauses in a sentence. We got that from German, which got it from Latin.
I still don't understand why English chose to omit commas in some cases. It just confuses the reader of larger sentences. In some fiction books the omission made some sentences completely unreadable. Granted, it was the author's fault but still... Why?
Too much emphasis/use of bold, overuse of actual/actually.
A lot of the tips in this article are very similar to the ones provided in this fantastic book: The Elements of Style [1]. I highly recommend it, even for a non-native speaker.
[1] https://www.amazon.com/Elements-Style-Fourth-William-Strunk/...
This post is a great set of ideas for writing. What the author is doing is constantly putting himself in the shoes of the readers, and thinking “what does the reader need here?”.
Which may sound like a very tortuous way to write. But it becomes instinctual after a while. When I’m writing and don’t apply rules like this, I inevitably feel lost - and I know the reader will be too. When I end up going down a bad road like this, at some point I will throw away most or all of what I’ve written and start from a fresh perspective. I guess this would be my one addition to the author’s rules: don’t be afraid to throw away lines, paragraph, or even the whole thing if it’s not working for you.
This is a fantastic list of like, "suggestions to writers by editors" but I don't think it's a great list of "how to edit." The single most important thing when editing (imo) is "how can I preserve the author's voice?" Editing is not writing a new draft, it's amplifying the original.
Don’t use adverbs
There is nothing inherently wrong with adverbs. They are just part of a category of things that I believe are lazy in writing.
Comparing this quote to the rest of the article, it appears the italics convey vocal emphasis. I find it somewhat ironic that “inherently” is an adverb.
This gets even worse in software code. When "Naming things" is hard, and two people name the same thing, they'll very likely give it a different name. A guarantee to maintenance nightmares.
DDD by Eric Evans suggests using Ubiquitous Language. Even when I don't use anything from DDD, I always add a dictionary.md in which we write down the domain terms. What is a Customer? What does a "Loan Application" mean. What can we do to a loan application and how do we call those actions?
It's one of the easiest tricks, that dictionary.md, but with great effect.
Why not put those definitions into the code, next to the types that define those entities?
Your term may not map cleanly to a single OOP class, and it may also be used in other function/variable names. There's also how you will express yourself in the code comments.
I mean, I'm guessing the dictionary is not just for nouns, but also verbs and adverbs. What will "transact" usually mean in this codebase? What will "safely" mean?
That's not really an argument, as it will map to either entities or functions, both of which can be annotated with this information.
An argument against documenting it on the entities and functions would be that this would spread the information across the repository. The value you get from doing this in a single markdown file is the overview it provides, I think.
These kinds of methodologies enable development with high turnover in large enterprise, which treat developers more like cogs that temporarily work on a given software. And if it's just a comment on a file, it'll likely not even be seen
No, it might not map to entities or functions. It could refer to concepts about the project that are not mapped in the code, but are still important to communicate with the team, the customers, and so on.
And even for terms that do map to entities and functions, it would be a bad idea to have the developers (and especially non developrs) hunt them around (even if it's just a grep away). As you say, the overview is important.
Even small teams of 4-10 people can benefit from shared common terminology, especially if each might work in different repos (or e.g. backend and front-end).
The team size has very little impact on it's value, it's entirely dependent on the turnover of the developers. I guess I wasn't clear enough as it seems you didn't understand what I meant to express at all.
With every sentence you wrote I just had another question mark appear over my head
I'm not sure what you think I didn't get - or what new questions appeared over your head. It's quite simple. You said 3 things:
1) You answered to the parent that whether "term may not map cleanly to a single OOP class" doesn't matter, because "it will map to either entities or functions".
My answer was that it might not map to those either, but still be useful to talk about the software, and good to be shared by the developers and other shareholders like UX and sales.
2) That "An argument against documenting it on the entities and functions would be that this would spread the information across the repository", and having a single markdown file gives better overview.
I agreed, and even expounded on that: "it would be a bad idea to have the developers (and especially non developrs) hunt them around (even if it's just a grep away). As you say, the overview is important."
3) That "these kinds of methodologies enable development with high turnover in large enterprise, which treat developers more like cogs that temporarily work on a given software. And if it's just a comment on a file, it'll likely not even be seen"
And I retorted that even smaller teams - meaning teams that don't are anything like the above, including not having high turnover, can benefit from this. Even without any turnover, people forget. So when getting back to further develop or debug or refactor, etc, some piece software it's good to have documentation of key types, concepts, and terminology, from when you originally wrote it.
- Not all project-related terms map to types
- The "types that define those entities" (that do map) can be scaterred across multiple source code files (so this would also scatter the definitions)
- The code is not where people look for reference, even more so for non-coders that still need to refer to the same things (e.g. UX, sales)
- The definitions that do map to types, could still be reusable in multiple code projects. Putting them in the code means you need to repeat them, make sure they're consistent, and sync them across codebases when some definition is changed/improved.
-
The last 3 points make a lot of sense.
The first one however I don't understand. Do you mind to give one or two concrete examples of that?
Not everything about a project maps to a type.
The team might have to handle the issue (and have a way to talk about the problem) of back-pressure for example. Doesn't mean there's a back-pressure type in the server code, or a "back-pressure-handler" class or something like that.
And that's still a term referring to a core tech aspect. There are terms related to projects that teams need to agree on that are appplicable to the sales or marketing or user documentation of the software, and not classes.
For a large part, this can work. But there are several cases where it doesn't. Modules, subdirectories, a group of classes, etc. Too often, at least a part of the terms don't have a logical place to go in code. I consider it worse to have them partly here and partly there, than to have them all together.
But, indeed, I often repeat the definition or naming in the class documentation, module file, methods etc. Knowing fully well it will drift, but accepting it does. And everyone knows the canonical place is dictionary.md, inline docs are merely reminders or copies of that canonical place.
I tried to introduce that, but few if any people stuck to it and still they came up with their own words and different understanding of the words that were already in the glossary I had created. It felt like they did not care much.
If software people don't care about using the business-domain-language, I think they are very bad software developers. The main task of software developers is to be the bridge between the domain and computers.
I've met and seen my share of teams that don't want to be that bridge, or offload it to "product owners" or "managers". They are -without exception- abysmal projects, terrible products and quite often have a poor UX. I refuse to call these people software developers, instead I refer to them as code-monkeys. And with all the generative AI going on, these are the first to be replaced by robots in our fields.
It doesn’t sound hard for LLMs to act as a domain-computer bridge.
Indeed a very important tip.
I'd also add that repeated ideas should be parallel, most commonly when you have multiple list items they should be presented "similarly", e.g.
Another problem I often see is documents or presentations that don't have a coherent narrative, where the ideas presented feel disjointed or random. As much as possible, each sentence should clearly lead to the next one and have a clear relation to it. Each idea should clearly lead to the next one and have a clear relation to it. Where things don't feel related, make sure to explain how they are related.As a simplified example (since this is hard to explain), when talking about a new service you intend to introduce you may talk about things like plans for scalability, reliability, error handling and cost. If you just talk about these things with no relevant introduction, they will feel random, but if you introduce them ahead of time with an overview of the relevant considerations they will feel more grounded. Additionally, you may want to discuss cost after scalability since the ideas follow from each other (maybe even scalability->reliability->cost to explain what we can do for reliability at different scales, and then finally the cost for each scale and threshold of reliability), whereas error handling is usually a technical decision that you may want to separate out to a separate discussion.
“Ugly” and “unstable” are not reasons, “ugliness” and “instability” are. You’re also not helping your argument by choosing such a derogatory example.
Huge vendors make this mistake across their entire system. Like data bricks with Workflows and Jobs (same thing). Super irritating, friggin’ pick one.
Another problem is semantic drift. It often happens that the thing that is named drifts in scope over time, but the name remains. Sometimes the name becomes just subtly mismatched, sometimes the relation to the original concept becomes completely lost. It’s useful for documentation to recognize this and explain the provenance of the name, because otherwise the mismatch is prone to cause confusion, irritation, or misunderstandings.
But if there ARE different names, call it out in the introduction, and state which one you will be using.
It's amazing that much of this has to be said, but here's a related piece of advice: don't use the same term for different things, especially if they're related.
I got a document the other day that described a category which consisted of 3 subcategories, one of which had the exact same name as the category it belonged to.
I felt like I had slipped into another dimension.
The flip side of "don't use different names for the same thing" is "don't use the same/similar name for different things."