Microsoft launches its new documentation site, and it’s very good

Microsoft has announced the preview release of its documentation service, https://docs.microsoft.com, which currently provides content for its Enterprise Mobility products.

“We interviewed and surveyed hundreds of developers and IT Pros and sifted through your website feedback over the years on UserVoice. It was clear we needed to make a change and create a modern web experience for content…For years customers have told us to go beyond walls of text with feature-level content and help them implement solutions to their business problems.” (source)

The key features are:

  • Improved readability
    • “To improve content readability, we changed the site to have a set content width.”
    • “We’ve also increased the font size for the left navigation and the text itself.”
  • Including an estimated reading time
  • Adding a publication date
  • Improved navigation
    • It is now based around sections on evaluating, getting started, planning, deploying, managing and troubleshooting
  • Shortened article length per page
  • Responsive Web Design
  • Community contributions
    • “Every article has an Edit button that takes you to the source Markdown file in GitHub, where you can easily submit a pull request to fix or improve content.”
  • Feedback mechanisms
    • To provide comments and annotations on all of the articles
  • Friendly URLs
  • Website theming
    • You can change between a light and dark theme

Wow – this matches closely with the topics we cover in our Advanced technical writing & new trends in technical communication training course, where we look at the changes made by other organisations.

Although it doesn’t mention it in its announcement, Microsoft has also made changes to the style of its topic headings and content. There’s frequent use of words and phrases such as “protect”, “discover” and “understand and explore”.

We’ve yet to look at the site in detail, but initial impressions are very positive.

What do you think?

The Internet of Things – creating a user guide for a fridge door

The Internet of Things (IoT) is, according to Wikipedia, the network of physical objects – devices, vehicles, buildings and other items – embedded with electronics, software, sensors, and network connectivity that enables these objects to collect and exchange data. The popular example is the concept of a smart fridge that could warn you when it was out of milk.

Yesterday, we spotted a tweet mentioning SeeNote, a digital version of the sticky notes people use around the house and office.

This got us wondering if it were possible to create a digital user guide that could be:

  • Stuck on the wall (or the fridge door)
  • Have a screen that was always on
  • Automatically update itself
  • Notify you when there was new information
  • Run without mains power for approximately a month between charges.

The SeeNote is a little too small for that purpose, so could another e-ink device, such as an ebook reader, be configured to work in this way?

Continue reading

MadWorld 2016 Conference Review – Day One

Last week, I spoke at, and attended, Madworld 2016, the conference hosted by MadCap Software for its users. It’s the most rewarding and enjoyable of all the conferences on technical communication that I attend. Here is a summary of what I saw and heard on the first day.

Continue reading

Perfecting collaborative authoring for online Help

Yesterday, I wrote:

“There are some activities that seem like they always could be improved. One is creating an authoring environment where professional technical communicators and other staff can work together.”

Writing online Help is different from writing some other types of content, in that it involves topic-based authoring. Content is stored in modular, re-usable and flexible chunks of information. By moving away from a page-centric, document model, you’re able to organise and present published information in many different ways. However, it’s a different approach to what many non-professional Technical Authors are used to. Unfamiliarity with this content model, as well as the tools, can make collaboration difficult.

Continue reading

The return of Clippy?

Are we seeing the the spiritual child of Clippy emerge? Truth Labs’s Stelios Constantinides has written an article on his experiments with conversational UIs.

Conversational user interfaces (CUIs) are a spoken or written way of interacting with a device. CUIs aren’t completely new, but they’re becoming smarter, more natural, and — therefore — more useful.

Here’s where CUIs come in: since users already spend so much time in apps like Slack, Facebook Messenger, and even plain-old email, why not integrate your app inside these platforms?

Microsoft ClippyConstantinides  looks at the design process of creating something that doesn’t come across as a robot, and isn’t as annoying as Microsoft Clippy.

This links in with Ann Rockley’s concept of Intelligent Content: “Content that’s structurally rich and semantically categorized and therefore automatically discoverable, reusable, reconfigurable, and adaptable.”

For conversational user interfaces to work well, they need to be automatically discoverable, adaptable and semantically categorized. Microsoft Clippy wasn’t, which is one of the reasons why it failed in its purpose.

It’s still unclear whether this will lead to content being seen as code, or stored in a semantically rich format and inside a content management system. Whichever way, it’s important to recognize that the conversational language is different from written language. We speak differently from the way we write, and this is reflected in how we use messaging apps and authoring tools. Conversations are typically a one-to-one form of communication.

With Siri, Google Voice and Cortana closed off to most developers, we’re likely to see conversational user interfaces developed as alternatives to these applications.

One school of thought is users will move away from searching using sentences, and, instead,  learn to type commands (they will write command line instructions). In other words, they will begin to think and type more like programmers. This is illustrated in the image below.

Slack command line

I wonder if this might be a bit optimistic. There are many people find Twitter too difficult to use, and I suspect it would take them a long time to adapt to this approach.


This topic is something we cover (albeit briefly) in our Advanced technical writing & new trends in technical communication training course (the next one of which is on the 22nd of March).

See also:

(With thanks to Simon Bostock)

What do you think? Share your thoughts using the comment box below.

API documentation design patterns

One of the current developments in technical communication is the development of a common way to present API documentation. At present, there are a number of different design patterns that organisations are using, but, as with many things, there seems to be a desire to establish a de facto standard.

One part of this has been to establish the topics that should be covered in an API guide. Typically, this includes a conceptual overview, how to obtain authorisation keys, getting started and the important reference information of the endpoints, parameters code samples and error codes. The reference information includes having code samples that developers can copy and paste (and tweak to their situation). This often means different samples for each development environment.

The second part has been the the information design aspects of how the content should be presented. The Stripe API is one that probably has been copied the most. This organises the content into columns, with the code samples on the right side of the screen.

Last week, Tom Johnson tweeted about a new design pattern used by Lucybot:

This offers a console, accessible as a tab.

Lucybot example API Console2

This is quite an appealing approach because it could be replicated across a number of authoring tools.

The UK’s Government Digital Service is looking to establish a common standard for API documentation on the Gov.uk website, and this could have quite an influence on other sites looking for best practice to copy.

Which design patterns have you seen and liked? Share your thoughts using the comment box below.

Summary of the findings from our 2016 technical communications survey

We asked Technical Authors to complete a survey into the issues and challenges they face in 2016 and beyond. There were four main themes that stood out:

  1. Issues around working in an Agile environment.
  2. A need to develop skills in creating training screencasts. This included how to use tools, structuring and presenting content, and the ideal length of each video.
  3. Improving the status of Technical Authors and the Technical Publications department in the organisation. This topic has come up in previous surveys.
  4. Developing skills in using DITA.

We’ve looked at Agile recently, and we’ll revisit the other topics in the upcoming months.

Thanks to everyone who took part in the survey.

Being Agile in technical documentation – Part two

Two years ago, we wrote a number of posts, and an Adobe-sponsored whitepaper, on Agile and its effects on technical communication. This topic was picked by others, including Sarah O’Keefe and Mattias Sander, who made further suggestions. We thought it was time to revisit this topic, and expand on some of the issues raised.

In Part one, we looked at Agile and the Lean method’s principles of maximising value and minimising waste. Here in Part two, we look at how we can minimise waste in the document production process.


Removing waste from user’s interaction with the product

Let’s briefly touch on value and waste during the use of the product by the user.

User Assistance can contribute to the user being less “wasteful” when they’re using the product: minimising the time having to stop when they get stuck, or having to rework things to fix mistakes. This means you need to provide the right information at the right time, in the right place, and in the right format.

It needs to provide the required information to the reader as fast as possible. In practice, this can mean having the Help embedded in the application itself. It might also mean creating different documents to suit different audiences, or even personalised content. It also implies User Assistance needs to be as short as possible, but not shorter.

This also means you’ll need to carry out some usability testing of the content and perhaps even A/B testing. You have to test to check what you’re producing is what gives value to users.

Removing waste from user documentation process

Let’s look at how we could apply Lean principles to writing technical documentation in an Agile environment.

Is it needed?

The Lean approach can help us identify which parts to document, and which to leave out. Under Lean, you should only document what customers tell you is absolutely necessary. Only information that adds value to the user, or increases their productivity, should be included. If the information isn’t needed by anyone, we shouldn’t write it (unless we have to do it for legal or other reasons).

By going through a design process of empathy, defining needs, generating ideas, prototyping and testing, we can identify the best way to solve a specific problem. In practice, User Assistance (in other words, the online Help and user documentation) should be considered part of the product design, and included in the initial design planning, rather than being left to the end. This requires a change in product planning thinking, as documentation is often treated as an afterthought, pushed to the end of the development process.

In an Agile development process, designers will create Use Cases for each feature, and technical communicators can do something similar. Use Cases can be used in the planning of User Assistance to identify who will use it (the audience), what value it will provide (or what problem it will solve), and when they will use it.

Load levelling

In addition to the waste of “non-value adding work”, in our simplified description of Lean there are also wastes of “overburden” and “unevenness”. These relate to having too much work to do in the timescales allowed, and having to stop and wait for something you need in order to carry on working. Instead, our goal is to have a consistent, productive rhythm to our work.

For technical communicators, this “overburden” and “unevenness” could be waiting for reviews, waiting for edits, waiting for work, or waiting for approvals. It can also mean wasting time having to switch tools or stop and start different tasks. If we can measure these wastes, we can justify the need to change working practices.

Levelling allows a consistent workflow, which makes it possible to set standards and identify abnormalities. The Lean methodology contains a number of techniques for smoothing out a work schedule, such as a triage approach to prioritising new work requests. One of the key ways we can level the technical writing workload is simply to start the project earlier. The benefits from avoiding having to stop and start, or rush things at the end, may outweigh any waste from having to go back and amend some of the content written at the start of the project.

One-piece flow

Related to load levelling is continuous, or one-piece, flow. W. Edwards Deming proved in the 1950s that implementing a continuous flow system, instead of working in batches, can have a significant impact on improving quality and reducing throughput time.

A continuous flow system works like serving people food from a counter. Customers move forward, picking up their stater, main course and pudding as they go down the line. When a serving station runs out of food, there should be a new tray of supplies ready to replenish it just in time to serve the next customer. People only work on one piece at a time and only one piece of work moves from one stage to the next.

Deming proved one-piece flow results in fewer bottlenecks, less waiting and faster throughput. You pull work from the previous step when you have available resources. It also means that mistakes appear earlier. As items are pulled one piece at a time, you should have one only faulty item to deal with, rather than a large batch of defects. If you fix the problem, identifying what caused it, it goes away before it can escalate.

One example of technical communicators working in batches is when they send out drafts of whole manuals to reviewers. One piece flow could mean passing on content for review in smaller pieces – perhaps even issuing content for review on a daily basis, making it an integral part of the product development process.

Kanban

One of the tools used in both Lean and Agile projects is a Kanban board. This is a visual representation of the pieces flowing through the process. It can help the team identify any problems, and control and regulate the amount of new tasks given to the team. It can be the case that no new work is added to the board until a current work piece is defined as “done”.

One approach is to include the technical writing task in the project Kanban board. This could mean if there are problems with creating documentation, these are brought to the surface for fixing there and then.

Alerting and fixing any problems early

The philosophy of both Lean and Agile is to bring problems and defects to the front, and force people to confront them and fix the immediate and underlying problems.

Within Lean, and often in Agile, when a problem or issue is identified, everyone is empowered to stop the process, and swarm around the problem to solve it immediately. So could a technical communicator have the right to flag to stop the process? Would a development team be willing to face up to the sheer amount of documentation and work with the technical communicator to tackle the problem? The answer should be yes, but it would depend on how closely the team adheres to Agile principles. For this to happen, the team needs to have an authoring system that enables non-professional technical communicators (such as developers) to be able to contribute content.

Dealing with variations in project plans

Technical communicators need to avoid having to pull the emergency cord, and this means they need to be able to deal with some of the variations that can arise as projects change over time.

In Part three

In Part three of this series, we’ll look at how we can modify our writing process and tools so we can implement these approaches into how we work.