5 ms·

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.

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.

berkes 3y ago
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.
- valenterry 3y ago
  Why not put those definitions into the code, next to the types that define those entities?
  - medstrom 3y ago
    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?
    - ffsm8 3y ago
      > Your term may not map cleanly to a single OOP class 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
      - coldtea 3y ago
        >That's not really an argument, as it will map to either entities or functions, both of which can be annotated with this information. 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).
        ffsm8 3y ago
        > Even small teams of 4-10 people can benefit from shared common terminology 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
        coldtea 3y ago
        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.
  - coldtea 3y ago
    - 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. -
    - valenterry 3y ago
      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?
      - coldtea 3y ago
        >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.
  - berkes 3y ago
    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.
- zelphirkalt 3y ago
  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.
  - berkes 3y ago
    > 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.
    - keybored 3y ago
      It doesn’t sound hard for LLMs to act as a domain-computer bridge.
Adverblessly 3y ago
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. 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 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.
- layer8 3y ago
  “Ugly” and “unstable” are not reasons, “ugliness” and “instability” are. You’re also not helping your argument by choosing such a derogatory example.
layer8 3y ago
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.
cookie_monsta 3y ago
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.
euroderf 3y ago
> don’t use different names for the same thing. But if there ARE different names, call it out in the introduction, and state which one you will be using.
vundercind 3y ago
Huge vendors make this mistake across their entire system. Like data bricks with Workflows and Jobs (same thing). Super irritating, friggin’ pick one.
anamax 3y ago
The flip side of "don't use different names for the same thing" is "don't use the same/similar name for different things."

berkes 3y ago

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.

valenterry 3y ago
Why not put those definitions into the code, next to the types that define those entities?
- medstrom 3y ago
  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?
  - ffsm8 3y ago
    > Your term may not map cleanly to a single OOP class 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
    - coldtea 3y ago
      >That's not really an argument, as it will map to either entities or functions, both of which can be annotated with this information. 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).
      - ffsm8 3y ago
        > Even small teams of 4-10 people can benefit from shared common terminology 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
        coldtea 3y ago
        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.
- coldtea 3y ago
  - 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. -
  - valenterry 3y ago
    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?
    - coldtea 3y ago
      >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.
- berkes 3y ago
  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.
zelphirkalt 3y ago
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.
- berkes 3y ago
  > 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.
  - keybored 3y ago
    It doesn’t sound hard for LLMs to act as a domain-computer bridge.

Adverblessly 3y ago

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

layer8 3y ago
“Ugly” and “unstable” are not reasons, “ugliness” and “instability” are. You’re also not helping your argument by choosing such a derogatory example.

layer8 3y ago

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.

cookie_monsta 3y ago

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.

euroderf 3y ago

> don’t use different names for the same thing. But if there ARE different names, call it out in the introduction, and state which one you will be using.

vundercind 3y ago

Huge vendors make this mistake across their entire system. Like data bricks with Workflows and Jobs (same thing). Super irritating, friggin’ pick one.

anamax 3y ago

The flip side of "don't use different names for the same thing" is "don't use the same/similar name for different things."