> In this time, I’ve read various resources on technical writing and documentation. These are my notes, both to help me remember later, but also as a tool to help me think about writing now.
and later, in an apparent contradiction ...
> You don’t need to tell the reader what you’re going to tell them. Just tell them.
I think this point could be fleshed out better.
Any piece of nonfiction writing, technical or otherwise, that doesn't give me a clear idea about its content may not pass my filter. I see this the most in long-form journalism. But it also pops up when authors focus on themselves, their struggles, and their aspirations in the first couple of paragraphs.
Telling the reader what they're about to read in the first paragraph of a technical piece is a courtesy. People are busy, and they don't have time to wade through a bunch of throat-clearing at the start of a piece. They'll just close the tab and move on.
This is a good counterpoint. After all, academic journals have abstracts for a reason--when people need to get something done, a synopsis quickly helps them make a decision as to whether or not they actually found the appropriate resource.
It goes both ways. I think this aspect of the craft is a bit more of an art than a science. At certain points it's appropriate to signal what you're about to discuss, at others, it's just noise.
In general, anything that functions similarly to an academic abstract is probably useful (saves the reader from potentially wasting time, gives an overview of the general subject matter and idea without delving into details, takes about 1 minute maximum to read).
Abstract or "executive summary" is the paragraph right under the title that does this in everything I wrote for the exact purpose to give someone the opportunity to see whether this is his/her go-to document for a purpose or note. I always like to add/read the ToC, that is also a quick read to see if this doc is what I am/people are looking for.
I've also noticed that for some reason people get sloppy when writing posts about technical writing and forget to apply the principles of technical writing to that post. I avoid this bad habit by forcing myself to provide a summary for every post I create, e.g. https://kayce.basqu.es/blog/FAQs/
>I've also noticed that for some reason people get sloppy when writing posts about technical writing and forget to apply the principles of technical writing to that post.
Well, technically meta-posts about technical writing are not technical writing.
Any piece about writing will violate its own rules. I think this could be a law ;)
This is because writing is hard. It is just like coding, in the sense that I can revise it three times and still find ways to make it better the fourth time, or the tenth time.
So no writing is perfect, but I think I can often tell when a writer has read the right books (like On Writing Well). Every now and then an article will jump out to me as being 10 times more lucid and concise than the norm --- even though it's still imperfect.
Also I think the rules are not black and white. There is some judgment needed at every turn. Sometimes you will want to bend one rule to preserve another, and people with different tastes will either praise you or blame you for how you make the call.
I like the rule of three. Tell the reader what you are going to tell and why. Tell them in detail. Then in the conclusion summarize the main takeaway from what you just told them.
I've never understood the pre-summarization technique. I've had lecturers constantly state what they intend to say so much that its a distraction. When I see this style of writing I glaze over as well.
You haven't been spending too much time with COOs, CAE, CCOs, and other Cxx's. They need the executive summary (pre-summarization).
Some of the C-folk like:
-single line (title)
-one liner (more than 5 words but less than 20 words)
-short paragraph (2-4 lines)
-perhaps a RAG or something visual that will show sentiment (if/where appropriate)
and they won't read past that.
So when (I) write documentation/report/what-have-you I need to make one document for all audiences, the Cxx with 1-minute to spend and the actual target/doer that will spend X-days following up the darn thing.
You pre-summarize, because you tell someone something, you tell them why you are telling them. So they can judge whether it is worth reading on. And to tell someone why, you have to state in a sentence or two what you are going to tell them.
The good thing about technical documents is that you can just skip the parts you don't want to read. But it is there for the people who do want to.
I don't think it's an apparent contradiction. The first quote is a meta description of the whole article. People would need to know what it's about to read it.
In actual technical documentation, on the other hand, people already know "this is the documentation of program X". And in the various chapters, you can just go ahead and give them a good title, and then go say what it is to say - without first announcing what you'll say.
and later, in an apparent contradiction ...
> You don’t need to tell the reader what you’re going to tell them. Just tell them.
I think this point could be fleshed out better.
Any piece of nonfiction writing, technical or otherwise, that doesn't give me a clear idea about its content may not pass my filter. I see this the most in long-form journalism. But it also pops up when authors focus on themselves, their struggles, and their aspirations in the first couple of paragraphs.
Telling the reader what they're about to read in the first paragraph of a technical piece is a courtesy. People are busy, and they don't have time to wade through a bunch of throat-clearing at the start of a piece. They'll just close the tab and move on.