Hacker News Reader

Comment by kaycebasques | Hacker News Reader

Technical writer with 10 years of experience. The way this post starts off talking about grammar is a yellow flag for me, if not red. Many developers/engineers get scared of technical writing precisely because of their fear of not using grammar correctly. Don't worry about that!! Just remember the cardinal rules of technical writing:

1. Know your audience. Talk to them. Look at their Stack Overflow questions. Analyze your documentation website usage. Run surveys. Make it easy for them to provide feedback.

2. Write for that audience's needs. https://diataxis.fr is a great start because those 4 needs cover 90% of the most common developer needs.

Documentation is a profoundly effective way to help people. Don't worry about doing it perfectly. Just stay focused on being helpful and of service.

View on HN

> The way this post starts off talking about grammar is a yellow flag for me, if not red.

I thought the post was full of useful guidance. I'm not sure what you mean with the comment about flag color. I tend to use terms like "red flag" to mean "Something is seriously amiss; perhaps I should look elsewhere for good advice.", but that doesn't seem to apply here: covering grammar in an article whose audience is people who write as part of their profession seems completely appropriate. Conversely, I'm not sure I agree with the advice that it's OK to simply not worry about it. Perhaps it depends on the experience level the guide is targeting. There are certainly more important aspects to technical documentation than grammar!

FWIW, I end up tripping over others' grammar errors far too frequently for my own comfort, though. When I've asked, it's not that they don't know in most cases, just that they don't think it matters. I tend to care both because it reads more smoothly, and because it indicates they paid attention to their work (something I value greatly). Not definitive, but certainly a strong signal.

That said, my grammar is rarely perfect, and I strongly agree that focusing on helping others is the real objective here.

The post is called technical writing for developers and then the post starts off with the very topic that intimidates and discourages a lot of developers / engineers: grammar. Putting it at the top implies it is the most important idea (see the journalism principle of the inverted pyramid for rationale). That is the red flag. My usage of that term is the same as yours. My point is precisely to not let worries about incorrect grammar stop developers from trying to create documentation. Focusing on grammar is textbook "missing the forest for the trees". There are so many more important / more fundamental ideas in technical writing than grammar. Of course you will eventually need to learn grammar to become an expert technical writer.

Grammar is not the most important thing, but it's hard to exemplify tone and voice without having the common language to talk about them and grammar is that language. I'm guessing the article starts with it because tone and voice is the most universal aspect, not because it's the most important aspect to technical writing. The rest are very hands-on details but that might not apply to everyone.

The two-axis diagram on diataxis is a great way to categorize documentation and all of them have different needs and indeed call for different voices. I have seen a number of projects where the only documentation produced is tutorials or itch-scratching posts for this one thing, and then when a feature changes somewhere you have a mountain of out-of-date information because everything was hard-wired to this combination of dependencies, versions and circumstances (whereas a manual could have been updated quickly and that would be that). And on the flip side, plenty of projects where there is a dense compendium for every detail and it's hard amid all the implementation details of the clustering gossip protocol versioning to find the little list of items you want to know to set the thing up to begin with - linked to the particular sections to read more about installation, configuration, backup, etc.

Over at his Computer Things newsletter[1], Hillel Wayne offers up some additional kinds of documentation worth adding to the four-document model. He lists five, but goes into detail on two: Conceptual Overviews are intended for beginners. They walk through all the concepts at a very high level. They provide no guide on “how,” avoid jargon, and can be understood by outsiders. Case Studies are examples that explore interesting or complicated problems in applying the concepts documented. An example is intentionally simplified, sometimes toy problems. A case study will show how to use the concepts on problems taken from real world uses.

1 https://buttondown.email/hillelwayne/archive/beyond-the-four...

> Technical writer with 10 years of experience.

What's an easy-to-remember trick for semicolon usage?

Consider when you have two distinct statements that are related but the former does not necessarily lead into the latter; a semicolon is appropriate in such an instance.

Alternatively, just don't bother and use two sentences.

I like to use a long dash instead. It gives the two statements more breathing room.

It's called an em dash. It's a dash the width of the "M" glyph.

https://www.thepunctuationguide.com/em-dash.html

No one really cares.

You're not going to lose a reader over semicolon misuse if you're solving a problem for them.

Dev with a flair for writing over here. Using semicolons is a good practice for separating clauses, especially if you're being verbose

My mother gave me my first car; it was an beautiful 2002 Honda Civic with a falling-off bumper and bald tires.

You could replace the semicolon with a comma thus:

My mother gave me my first car, a beautiful 2002 Honda Civic with a falling-off bumper and bald tires.

That feels a little more natural, but is harder to read accurately.

It's useful in legal and technical writing, but not necessarily great for everyday life. Personally, I don't really use semicolons; you may have different opinions on their usage.

It's basically an arrow in text.

this -> that

as opposed to a comma, which feels more like

this and also that

> Using semicolons is a good practice for separating clauses, especially if you're being verbose

Can't a period do that?

Yep. Sometimes that feels too abrupt, though. Even if you're trying to be pointed.

I like using these two ‘jokes’. Neither of them are actually funny, but they help (me).

- What is the difference between a semicolon and a cat??

One has a pause at the end of its clause. The other has claws at the end of its paws.

- What happened when the semicolon broke grammatical rules??

It got two consecutive sentences.

—-

All that said, it’s usually better not to. There aren’t really many cases in modern English where a semicolon is necessary. And there are even fewer cases where a semicolon provides a more clear expression than two sentences. In practice, they’re most often part of really badly disjointed ‘sentences’.

Don't use it.

Haha. Well said.

My mother has a PHD in English Literature and has taught languages and writing in college for decades. She's also a book editor and an author with published works from picture books for children to graduate-level text books. She tells me that the semi-colon's primary use is to let the reader know that the author attended college. Just use a period.

As T.S. Eliot said, great writers steal. That’s Kurt Vonnegut’s joke!

Don't use it; or do, I'm not your English teacher.

I only use it as an upgraded comma. The options are red, green, blue; cyan, magenta, yellow, black; or black and white.

You mean in JavaScript? ;)

Reply on news.ycombinator.com