Hacker News Reader

Comment by mattlutze | Hacker News Reader

After reading some of the comments here, I'm wondering if people are actually following the link and reviewing the content.

The two courses are well-structured. Each course has an overall outline listing each lesson, and each lesson has a table of contents to overview the topics therein. The courses highlight major key topics in technical writing and does so with easy-to-internalize (tenets). I'd have loved for my university coursework to be so clearly organized.

Some highlights include defining your audience[1], engaging your audience[2] and reviewing how short and clear sentences improve comprehension[3].

1: https://developers.google.com/tech-writing/one/audience#defi...

2: https://developers.google.com/tech-writing/one/active-voice

3: https://developers.google.com/tech-writing/one/short-sentenc...

View on HN

Your reference 1 is a deep-link that skips the intro. The intro says:

> The course designers believe that you are probably comfortable with mathematics. Therefore, this unit begins with an equation:

> good documentation = knowledge and skills your audience needs to do a task − your audience's current knowledge and skills

> In other words, make sure your document provides the information your audience needs that your audience doesn't already have. Therefore, this unit explains how to do the following: ...

This is the kind of fluff that turns many people off. Worse, it is confusing and tries to make a formula out of a sentence. The whole thing could’ve been replaced with the first sentence of the 3rd paragraph I quoted.

Your reference 2 contains this gem:

> Short sentences communicate more powerfully than long sentences, and short sentences are usually easier to understand than long sentences.

And the section title immediately after that sentence is:

> Focus each sentence on a single idea

Maybe that's the point? Education through irony?

tenets, not tenants.

added a lot of value there

pdr2020’s spelling-correcting comment indeed didn’t add much value, but as it was three words long, it also used up very little time and attention. I think such spelling-correcting comments don’t deserve the criticism you implied. The (minor) benefit of preventing mattlutze from making that particular spelling error in the future was well worth the (minor) effort of making them read a three-word comment.

For me, a non-native English speaker, it added value.

It is not a common word, I didn't know, and the way the GP included it was explanatory. Having "tenant" there would be very confusing, now, I just learned one more interesting.

In a post about writing, that's even on-topic.

Alright, I stand corrected.

Reply on news.ycombinator.com