General Data Protection Regulation – will this affect online Help?

Yesterday, I saw a presentation by Hazel Southwell on the EU’s General Data Protection Regulation (GDPR), which will be implemented on the 25th May 2018. The impact in its data privacy and protection rules seem likely to affect pretty much every website, with the threat of hefty fines for those that do not comply.

Organisations providing personalised Help content, by storing information in cookies or monitoring the behaviour of users living in the EU by tracking their digital activities, will need to comply with the GDPR regulations. In particular:

  • Businesses will have to adopt governance and accountability standards and meet their data privacy obligations.
  • Clear and affirmative consent to the processing of private data must be provided, and the relevant information must be laid out in simple terms.
  • Organisations need to consider the risks of transferring data (such as the storing of cookies or IP addresses) to countries outside of the EU.

One solution is to require users to log in to see information. However, this may be an unpopular and impractical solution for many users.

Update: The Internet of Things – creating a digital user guide to attach to a door

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.

Continue reading

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

Creating documentation in a Continuous Integration/Continuous Delivery environment

Creating user documentation and online Help in a Continuous Integration/Continuous Delivery environment can be challenging for technical communicators and developers.

Continue reading

One to watch – Swagger2markup

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.

Swagger2Markup screenshot

The output would look like this:

Swagger2Markup output

 

How to create online Help topics that are editable by clients

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:

  1. Transclusion
  2. Appending content to the bottom of a page
  3. 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.

Transclusion

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:

conref example

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.

madcap pulse main screen

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:

embedded topic example

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.

How technical documentation helps the customer journey

Here is a diagram that shows the different types of User Assistance that can help users as they progress through the customer journey:

how user assistance helps 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.