Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

What I think about when I edit (2019)

evaparish.com

Post reply on HN
Print view View original

41–50 of 138 posts

Re: What I think about when I edit (2019)

#41

Post by amenhotep »

jmmcd wrote: post #10

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 laugh…

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

Re: What I think about when I edit (2019)

#42

Post by Adverblessly »

KineticLensman wrote: post #9

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 resol…

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.

Re: What I think about when I edit (2019)

#43

Post by susam »

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.

Re: What I think about when I edit (2019)

#44

Post by coldtea »

valenterry wrote: post #19
berkes wrote: post #15

Earlier quoted context omitted.

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…

Why not put those definitions into the code, next to the types that define those entities?

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

-

Re: What I think about when I edit (2019)

#45

Post by HeavyStorm »

susam wrote: post #43

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…

A glossary is the most important document ANY project should have and maintain. Everything else is secondary.

Re: What I think about when I edit (2019)

#46

Post by coldtea »

ffsm8 wrote: post #33
medstrom wrote: post #26

Earlier quoted context omitted.

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?

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

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

Re: What I think about when I edit (2019)

#47

Post by layer8 »

KineticLensman wrote: post #9

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 resol…

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.

Re: What I think about when I edit (2019)

#48

Post by coldtea »

jmmcd wrote: post #10

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 laugh…

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

Re: What I think about when I edit (2019)

#50

Post by coldtea »

bregma wrote: post #36
hovering_nox wrote: post #16

Earlier quoted context omitted.

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

Post reply on HN