Following on from our post The Internet of Things – creating a user guide for a fridge door, we came across other ways to create e-ink digital user guides that could be attached to the door of meeting rooms, providing information on room bookings, using the equipment in the room etc.
The Language of Technical Communication book is a collaborative effort with fifty-two contributors defining the terms that form the core of technical communication as it is practiced today. Cherryleaf’s Ellis Pratt was one of the contributors.
Each contributed term has a concise definition, an importance statement, and an essay that describes why technical communicators need to know that term.
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 (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 eink display is exactly what i want: https://t.co/C6xQ8R9U6t
Excited to get one! pic.twitter.com/6VC7FKP1J9
— harper (@harper) April 26, 2016
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?
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.
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.
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?
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.
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).
- Clippy’s Revenge — Smart Messaging as Platform Shift
- 2016 will be the year of conversational commerce
(With thanks to Simon Bostock)
What do you think? Share your thoughts using the comment box below.
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:
— Tom Johnson (@tomjohnson) February 17, 2016
This offers a console, accessible as a tab.
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.