Documentation

When I began working in tech support, I relied on our knowledge base to get me through. If no one was around and I didn’t know the answer to a customer’s question, I’d scour the documentation for clues. I usually found what I was looking for, saving time and sanity. “No one should be a … Read more

Calgary rests 1,048 metres above sea level. This high altitude results in low air pressure, which makes cooking a wee bit longer than I’m used to. I honestly forgot about this when I moved here, so the first time my hard-boiled eggs came out soft came as a surprise. Back in Vancouver, I had it … Read more

Lists are common in technical writing. One of my duties is to instruct readers on what to do, step-by-step. Writing lists may seem easy, but I’ve seen a lot of manuals that ignore parallel sentences, emphasize words randomly, and forget punctuation. Bad example of a list These milk frother instructions came from a Nespresso Aeroccino manual. … Read more

A member of the Write the Docs Slack community asked for advice on designing buttons in a user guide. Her three options were: Quotes (e.g., Click “OK”) Brackets (e.g., Click [OK]) Bold font (e.g., Click OK) Everyone who responded advised the writer to use option three. This also corresponds to Microsoft Style Guide’s short article about the button. … Read more

In our Write the Docs Slack network, a member asked if we knew of any best practices on using the word “recommend” in technical documents. There are no official best practices, so we all had different suggestions, such as: Use sparingly, but when you do, state why you’re recommending it so users can decide if … Read more

I’m contributing to an open-source project on GitHub called Awesome, a curated list of interesting topics and their resources. Famous open-sourcer Sindre Sorhus wants help in writing descriptions for each item on the list, so I created a pull request for programming languages in the list. I thought my contributions would be helpful. Not quite. Mistake … Read more

While browsing through a tutorial online, I came across a link that said, “View guide.” The guide could have been a video or an article. I wasn’t sure what to expect. Since I was sitting in a quiet café without my headphones, I hesitated to click the link in case it was a video tutorial. … Read more

Q: Should I place my periods and commas inside or outside quotation marks? That depends on what style of English you follow. If you follow the British style, periods and commas can go inside or outside the quotation marks. But if you follow the American style, periods and commas stay inside the quotation marks. For … Read more

What is “Yes, and…”? “Yes, and…” is a rule-of-thumb that encourages a participant to listen to and build on an idea that another participant presents. This approach keeps the lines of communication open and fosters cooperation and friendship. For example, Alice starts the scene as a surgeon. Bob accepts this offer (the “yes”) and continues … Read more

I’m part of the Write the Docs (WTD) Slack channel, where technical communicators and other professionals who write the docs share ideas and knowledge. Every morning, I open the Slack channel and read the discussions so I can learn something new every day. Recently, one of the members asked how he should refer to the … Read more