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.

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.

> 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.

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.

Even better:

Get" rel="nofollow">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.

"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.

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.

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.

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.

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.

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.

- 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.

-

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.

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.

>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.

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 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.

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.

  BAD: Windows is a bad operating system for many reasons:
  * It is ugly
  * Unstable
  BETTER: Windows is a bad operating system for many reasons:
  * It is ugly
  * It is unstable
  OR: Windows is a bad operating system for many reasons:
  * Ugly
  * Unstable

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.

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.

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"

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.

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.

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.”

No, the original said "made", so I think they actually turned around.

A good story teller can both show and tell, depending on whatever fits the story, their stylistic choice, and their intention.

"He laughed with the kind of booming abandon that made the whole restaurant turn around and look, in the before-times."

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 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".

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).

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.

"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.

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'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.

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

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'?

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.

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".

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.

"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.

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.

Blisteringly good. Not aimed at technical writers, but encourages you to think about how to really use language effectively and robustly.

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.

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.

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 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.

> 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.

The other scenario is when the reader is not new, but it is too late to ask.

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.

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 can tighten it up, and tighten it up again, and sloppy doggerel becomes so clear.

Really a lovely piece of writing about writing.

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).

(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.)