Microsoft Writing Style Guide 2018: Procedures and formatting highlights

In 2018, we devoted several  posts to the latest writing style guide from Microsoft:

• Microsoft Manual of Style vs. Microsoft Writing Style Guide
• MMoS vs MSG: The old, the new, and the unexpected

Yet, Microsoft guidelines is the topic one can talk about endlesly, isn’t it? 🙂 This time, I decided to focus on a few aspects of procedure writing and formatting that grabbed my attention most.

Grab your favorite drink, turn up the sound, and don’t miss the quiz at the end of the video!

Here’s a sneak peek at the video highlights:

• Use device-neutral verbs.

Users may interact with your product using various devices and input methods.

• Minimize UI terminology (menu, tab, box, and similar.).

Fewer words make actions more clear. Compare these: “From the File menu, select the New option” and “Go to File > New”.

• Mind the look and feel of your text.

Proper combination of font size, line spacing, and capitalization makes your text more scannable and easy to follow. Microsoft provides specific formatting advice to get you started.

Do you use these guidelines in your docs and did they make a difference for you? Let us know in the comments!

Advertisements

TechComm and Artificial Intelligence (overview of a podcast by Seth Earley)

Nowadays, artificial intelligence is a central subject in the constantly evolving world of technologies. It is believed that in the long run, it will define the next generation of software solutions. Simultaneously, there is a lot of anxiety that Artificial Intelligence (AI) is going to lead to significant labor displacement.

So, in the context of Technical Communication, does the advance of AI mean that our trade is doomed to extinction as well?

Evaluating the effectiveness of your e-learning

Having planned your e-learning thoroughly—with the analysis of the training needs, audience, and tasks, storyboarding and prototyping, content creation and testing—it might cross your mind that publishing your course is actually THE END. Not that fast, my friend! Have you evaluated the effectiveness of your e-learning yet?

via GIPHY

Here are a few techniques to check if your e-learning is effective:

• Kirkpatrick Model
• ADDIE Model
• Learnability Framework

UX copywriting series. Dropbox feature descriptions

No matter what you’re writing—whether it’s a small tooltip or a long web article—you need to thoroughly check your writing before you publish it.

Good writing is not just about spelling, punctuation, and capitalization, though we definitely need to keep them in mind at all times, among like… a million other things.

During UI text review, InfoDevs point out things that non-professional writers would never think to think about. Today, I’d like to talk about the most typical things that we stumble upon during the UI text review.

Brace yourselves – it’s going to be a long article but a 100% practical one and so worth a read! We’re going to discuss 6 reasons why Dropbox feature descriptions did not pass our UI text review.

Leading by example in legacy projects

One of the typical ways for agreeing to have project documentation in place is this:

1. Customer voices the need for documentation (on a side note, product-based software companies are not considered in this discussion).
2. Documentation team provides the estimates.
3. Estimates are adjusted and approved.

This works well for new projects and new features in existing projects. On a side note, this also assumes that the people who give the final approval for documentation do understand why documentation is needed.

But what about legacy projects, the ones that are poorly documented or not documented at all? How do you convince the company (or the customer) that documentation is needed?

Creating custom Word dictionaries

Have you, fellow Word users, ever struggled with proofing your document that enlisted, let’s say, dozens of different platforms or development tools? We all know how tricky those names can be to spell. To make sure that in your document .NET is always spelled .NET and not .Net or .net, you can add the needed spelling to the Word global dictionary. But what if you have hundreds of terms? How to make sure that all of them are spelled correctly in a consistent manner? What if you will not need them once you finish your document? Too many questions, and CyberText Newsletter features a great article that answers them.

Operation Cleanup: CSS refactoring for InfoDevs

Hey, fellow writers who work in MadCap Flare! Have you ever opened your CSS style sheet in a text editor and checked if it contains conflicting entries, style duplicates, or empty style definitions? Maybe there are unnecessary repetitions of a property assigned to child elements, but this property is already assigned to a parent element? (I had this problem with fonts and colors).

Being unsure of what is going on with your CSS, you might be surprised to find that, for example, after you changed one property, half of your document inexplicably changed its color or indentation level. And there you are wasting time trying to apply a quick fix that most probably breaks something else. It is only then that you finally realize that the CSS refactoring time has come.