What I think about when I edit (2019)

Post by layer8 » Sat, Apr 06, 2024, 11:56 AM UTC

Adverblessly wrote: post #42

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

Post by wodenokoto » Sat, Apr 06, 2024, 11:58 AM UTC

publius_0xf3 wrote: post #32

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

Post by layer8 » Sat, Apr 06, 2024, 12:01 PM UTC

KineticLensman wrote: post #34

publius_0xf3 wrote: post #32

>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

Post by coldtea » Sat, Apr 06, 2024, 12:04 PM UTC

jmmcd wrote: post #22

wizzwizz4 wrote: post #14

Earlier quoted context omitted.

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.

Post by coldtea » Sat, Apr 06, 2024, 12:10 PM UTC

valenterry wrote: post #54

coldtea wrote: post #44

Earlier quoted context omitted.

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

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?