Ideas for quality content (summary + video)

Here in Lviv, we were lucky to invite Patrick Keegan, Principal User Assistance Developer at Oracle, and enjoy his talk “Free your mind! And your docs will follow”. It took me some time to digest the whirling ideas and grasp the insights.

In this post, I would like to share two approaches Patrick discussed during his presentation and how I plan to adopt them in my routine as an Information Developer.

Here we go.

Continue reading

Handing a documentation project to another Technical Communicator: tips & tricks

The phases of project initiation and project closure are substantially covered in blog posts, talks, and other resources across the TechComm society. Today, I would like to address a less frequently discussed phase – replacing a technical communicator in a project team.

Continue reading

Documentation as a prerequisite for successful CSIS

Complex System of Information Security (CSIS) comprises a set of organizational and technical measures aimed to ensure the protection of information circulating in the system from disclosure, leakage, and unauthorized access (c).

If your company is implementing the CSIS, it’s in for reinforced credibility and boosted sales. And you as a Technical Communicator are in for a bumpy ride. 😊

Let’s take a look at a grueling journey of meticulously described processes, roadmaps, and guidelines that need to accompany every stage of the System development.

Continue reading

Microsoft Writing Style Guide 2018: Procedures and formatting highlights

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

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!

blog post cover

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!

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?

Continue reading

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. Continue reading

Linear User Guide: Is It any Good?

Many believe that written user guides are doomed to extinction. Although their usage has diminished slightly, they are not clean gone yet. They are still with us—serving their particular audience and making us wonder what is the best approach to structuring them.

With the rise in the popularity of online documentation, many have ditched linearity and adopted a topic-based approach to writing—faster, more convenient, and definitely more efficient from the user perspective; absolutely challenging from the author perspective. But is such an approach still any good for structuring user guides which, unlike help systems, don’t provide immediate assistance to the user, differ in the very context of use, and are designed with a clear intention—to teach and guide?

Continue reading

MMoS vs MSG: The old, the new, and the unexpected

It’s been half a year since Microsoft released a new edition of their manual of style. The long-time reference of a few generations of technical communicators has been renamed, revamped, and rethought in several aspects.

It took us quite some time to grasp all the changes and ideas crafted by Microsoft, and in one of our previous posts, we’ve already summarized some of them. Now we would like to share our impressions about the new style guide in terms of its format, structure, and content.

Continue reading