101–110 of 138 posts
I would add eliminating future tense. There's very few times when future tense is actually required. It's one of my pet peeves when docs say something like "Click X. This will open a prompt ..." when it can say "Click x. This opens a prompt ..."
One of my pet peeves while reading technical documents is coming across acronyms that have not been introduced to the reader yet. When this happens over and over again across several documents of a project and people working on the project change over years, sometimes we end up in a situation where nobody can tell anymore what a particular acronym expands to. In fact, more than once, I have seen the bizarre situation…
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…
Hello everyone! This is my post! I'm flattered and honored that it resonated with many of you. Since I wrote that post, I followed my curiosity to become a software engineer myself. After doing that work for a few years, I've found myself missing working in a more writing-heavy role. If you're looking for an excellent technical writer, developer advocate, or another role that blends communication expertise and techni…
One question: after writing the sentence “I really got a lot out of the article.”, I wondered: is this extraneous? Is this clear? Am I saying precisely what I mean? And I think, yes, I meant exactly what I said, and I went into detail in the following sentence. I am just curious what you think.
> Whitespace is key for technical documentation but can also be used to great effect in blog posts, emails, and elsewhere. It’s hard for people to read long paragraphs, especially on a computer screen. They will zone out. 100%. The explanation (?) I first heard which helped me 'get' this whitespace principle was along the lines of > Have you reached a page in a book with no paragraph breaks and thought 'oh no'?
Hello everyone! This is my post! I'm flattered and honored that it resonated with many of you. Since I wrote that post, I followed my curiosity to become a software engineer myself. After doing that work for a few years, I've found myself missing working in a more writing-heavy role. If you're looking for an excellent technical writer, developer advocate, or another role that blends communication expertise and techni…
I really got a lot out of the article. I think it will help my write more succinctly and clearly and to be better understood. One question: after writing the sentence “I really got a lot out of the article.”, I wondered: is this extraneous? Is this clear? Am I saying precisely what I mean? And I think, yes, I meant exactly what I said, and I went into detail in the following sentence. I am just curious what you think…
One of my pet peeves while reading technical documents is coming across acronyms that have not been introduced to the reader yet. When this happens over and over again across several documents of a project and people working on the project change over years, sometimes we end up in a situation where nobody can tell anymore what a particular acronym expands to. In fact, more than once, I have seen the bizarre situation…
A glossary is the most important document ANY project should have and maintain. Everything else is secondary.
One of my pet peeves while reading technical documents is coming across acronyms that have not been introduced to the reader yet. When this happens over and over again across several documents of a project and people working on the project change over years, sometimes we end up in a situation where nobody can tell anymore what a particular acronym expands to. In fact, more than once, I have seen the bizarre situation…
"Let's talk all about a topic we will define three chapters from now"
Learning about things with undefined terms, concepts and acronyms is much harder and may require multiple passes over the material.
It's a hard part of writing a linear book about a topic that's probably a graph, but good writers manage it. Bad writers just leave their readers confused.
One of my pet peeves while reading technical documents is coming across acronyms that have not been introduced to the reader yet. When this happens over and over again across several documents of a project and people working on the project change over years, sometimes we end up in a situation where nobody can tell anymore what a particular acronym expands to. In fact, more than once, I have seen the bizarre situation…
I think the google guide to technical writing recommends to write out acronyms once per chapter/section.
Hello everyone! This is my post! I'm flattered and honored that it resonated with many of you. Since I wrote that post, I followed my curiosity to become a software engineer myself. After doing that work for a few years, I've found myself missing working in a more writing-heavy role. If you're looking for an excellent technical writer, developer advocate, or another role that blends communication expertise and techni…
I really got a lot out of the article. I think it will help my write more succinctly and clearly and to be better understood. One question: after writing the sentence “I really got a lot out of the article.”, I wondered: is this extraneous? Is this clear? Am I saying precisely what I mean? And I think, yes, I meant exactly what I said, and I went into detail in the following sentence. I am just curious what you think…
Your writing is not clear to me. Using the word “really” is extraneous. Using “I think” is also extraneous; I assumed these are your thoughts.
As the author notes, replace “it” with “the article”, or better yet a specific quote or idea distilled from the article.
Helped “my write” should be helped “me write”. You use two -ly adverbs, which could be avoided by restructuring the sentence.
You also have a list of two (succinct and clear) and then a single item (better understood). Consider breaking these two thoughts into separate sentences.