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 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?
Creating user documentation and online Help in a Continuous Integration/Continuous Delivery environment can be challenging for technical communicators and developers.
The results from the Stack Overflow 2016 survey have been announced this week. It identified poor documentation as the second most common workplace gripe for developers.
Swagger2Markup promises to simplify the generation of REST API documentation by combining auto-generated API documentation produced by Swagger with manually written content. To include the programmatically generated snippets in your documentation, you’d use Asciidoc’s Include macro.
The output would look like this:
In the Agile Technical Writers forum on LinkedIn, one of its members posted this question:
“I need to create an contextual online help for an complex web tool (ok, that´s not that hard). The customer must be able to add some specific job instructions to this online help by himself. The customer part must not be overridden when the online help is updated.”
LinkedIn’s forums provide limited functionality for long replies, so I thought I’d answer the question in more depth on our blog.
There are three main approaches you can take:
- Appending content to the bottom of a page
- Embedding empty placeholder topics within topics (which the client can use to add content)
You can also simply link to an external topic. However, in this case, they wanted the user content to appear with the official content.
In the DITA authoring standard, transclusion is called content referencing (or conref for short). It enables you to insert information from one topic into another. This means you can add customised content to a topic without having to make any changes to that target topic. You specify how the information is pushed into the existing topic: Insert the information just before an element; insert the information just after an element; or replace the information contained in an element. One of its strengths is, if you are adding new items to a list of steps, the list will renumber automatically.
Here is an illustration from our DITA training course:
The downside is writers need to be familiar with DITA, or be given a template to use.
Appending content to the bottom of a page
A common approach is to enable users to add comments and additional information at the bottom of each topic. This is the approach taken by tools such as Confluence, Mindtouch and MadCap Pulse.
This can work well. However, the information can be missed by it being at the bottom of the page, and if there are too many comments.
Embedding empty placeholder topics within topics
Another approach is to have empty topics within each topic. The two topics can be concatenated (joined) together to form a single topic. The client can add any client-specific content into the empty placeholder topic, so they don’t need to touch the topic containing the official content. This is sometimes called embedding topics within topics.
Here is an example of how local branch information is added to official documentation on fire safety procedures:
The advantage of this approach is that it can be done with simpler authoring tools than DITA (like markdown). The disadvantage is that you may not be able to preview the final topic (to do that, you’ll need to generate the whole document), and it won’t work as well for inserting content into numbered lists.
Do you use a different method?
Please share your thoughts below.
Here is a diagram that shows the different types of User Assistance that can help users as they progress through the customer journey:
Supporting the user through the customer journey has become more important, partly because the subscription, “try before you buy”, sales model means users can stop being a paying customer at a moment’s notice. Today, all of the information you provide, both pre- and post- sales, needs to provide the same consistent, high quality, experience to the user.
Have we missed anything out? Let us know if you think the image should be changed in any way.
Earlier this week, we were helping a large company finalise a bid document where they were required to use a Word file sent by their client. This involved taking content from the company’s repository of standard documents on SharePoint, and from emails, plus writing down information provided verbally by the Subject Matter Experts. The bid writing team had to cut the relevant content from a Word document (and emails, Excel spreadsheets, Visio files, Microsoft Project files and PowerPoint presentations), and then paste it into the bid document.
Before we started to work on the document, this had resulted in it containing a large amount of different formatting styles. For example, the content pasted from emails was in Calibri 10pt. font, and the content posted from Word was in Arial 11pt. This meant the bid writing team had to spend a lot of time remedying the formatting.
This method also meant there was no reliable way to embed content, like there is, for example, in Excel – if you change a cell in Excel, related cells in other places can update themselves automatically to reflect that change. For the bid document, any changes to the source content could trigger a further round of copying and pasting into our master document.