Hacker News Reader

To me as someone often reads documentation, the lack things outlined in that course make it harder. Not defining terms before using is something I sweared about a lot. Documentations with long complicated sentences are hard to follow.

I read the course, there were three clicks setup and then I was choosing topics to read about. I did not get lost and it was short. None of that seemed overkill to me.

Related are the atrocious user manuals and tutorials for various consumer electronics products. You get descriptions like "if the self-diagnostic tool shows the message 'no errors found', it means that there are no errors that the self-diagnostic can see." Or other manuals or help texts that just plain rephrase the prompt.

Good technical writing is much like teaching a great course: Empowering the reader to use the product or service for their own purposes.

Great comment about missing the forest from the trees. The course outline reminds me of an article on "writing great code" that lists the rules of a code formatter.

My personal tips for writing docs: 1. think about what you need to get across and to whom. I've found this categorization helpful (just don't get religious about it): https://www.writethedocs.org/videos/eu/2017/the-four-kinds-o... 2. try to say whatever you're saying with as few words as possible. "Vigorous writing is concise" is probably the best takeaway I got from Strunk & White (not a huge fan of the book otherwise) 3. do a few passes. "Keep rewriting" is probably the best takeaway I got from "On Writing Well" (but I like that book in general).

The trick to writing that works for me is to combine tips 2 and 3 iteratively. I don’t write concisely at first (and I think that’s the case for most people), so I just write down everything I can think of related to the topic, even all the edge cases. Then I go back and simplify, maybe focus on a relevant example. I cut out fluff and stick to that example, perhaps with the list of edge cases in a separate section (and call it “Advanced Use Cases”).

I like these 10 tips for clear writing from the GOV.UK team. The tips can be used by anyone to help their writing and are not specific to technical writing.

(To skip the podcast, scroll down the page to see the list of 10 tips)

https://gds.blog.gov.uk/2019/08/27/podcast-on-writing/

The 'Writing for GOV.UK' guide is also full of good writing advice for people publishing content on the web:

https://www.gov.uk/guidance/content-design/writing-for-gov-u...

Perhaps their newer products have gotten better but I've traditionally found Google's documentation to be case studies in how _not_ to write docs. Typically, they seem to be writen for ppl who understand the product and/or situation. You know, the type of ppl who don't need the docs.

I'm going to check this out. But looking to Google for advice on docs is like looking to Google for advice on design and/or UX. You don't bother. There are higher quality sources of such info.

These courses are typical tech-writer overkill, missing the forest for the trees, then getting lost in the weeds (if I may mix a few metaphors). There is too much introduction and setup, then it jumps into the nitty-gritty, but never gives the big picture.

The real challenge is that no one agrees what great writing really is or how to teach it. The problems are conceptual and related to the nature of writing, thinking, and communicating—all fields that are unsolved. I've taught writing in universities and written about the challenges of writing (and related grading challenges) before. https://jakeseliger.com/2014/12/20/subjectivity-in-writing-a...

"The big picture" is often the world itself.

I do agree that writing is a moving target. Different people learn in different ways, some people learn best from the style and content in the original submission. I’ve often thought that all docs should have a mirror video tutorial to give the same info for visual learners.

I disagree that the big picture is so broad. Your article about subjectivity is accurate, but it applies to the field of creative writing. For technical writing and to some extent journalism, they are almost defined by by their purpose in communicating a specific thing. That “thing” is the big picture.

> The real challenge is that no one agrees what great writing really is or how to teach it.

If the doc allows an average user to quickly setup the service and how to use it with two or three scenarios without getting confused is a good metric that the doc is good.

> To write documentation, you need 2 things: an understanding of the subject matter, and a high-level understanding of what the readers want to do.

Yes. But this list is incomplete. In fact, it's missing the two essential questions the go into _any_ communication:

1) Who is the audience?

2) What do / don't they already know?

How you explain what they want to do is a direct funtion of you they are and their current knowledge toolbox (if you will).

The vast majority of tech docs suck because too often the sender assumes the receiver is just like them. That is, the sender fails to put themselves aside; fails to put themselves in the shoes of the receiver.

Those are the trees I was talking about. Actually, 1) is subsumed by “what the reader wants to do,” and 2) is unknowable and you’ll write a hard-to-use doc covering all the cases (kinda like the original submission).

In my experience, all software has a purpose. For example, an API is for writing an app that gets and processes info from the server. That’s the big picture. The audience is someone writing that app. If they can’t write apps, it’s not the job of your doc to teach them. Aim the doc at the competent app-writer, give them useful info, and don’t add any fluff. In fact, if you provide a good API doc, it will teach beginners through good form and good examples.

Really interesting comment thanks! Do you have any more tips for improving in technical writing? Do you know of any other good book / course on this matter?