Is documentation a dirty word?

Daryl Colquhoun has written an article in tcWorld about the international standard ISO/IEC/IEEE 26512. He explained the standard is going to be revised and renamed: from “Systems and software engineering – Requirements for managers of user documentation” to “Systems and software engineering – Requirements for managers of information for users”.

The reason for this, he states, is because, in many parts of the world, the term “documentation” is associated with a printed manual only. The neutral term “information for users” refers to all types of content: Online help, audio, video, and Augmented Reality.

The problem with “information” is it can mean many things. Information for users could mean the weather forecast. We may well need to move away from the word documentation, but I’m not sure we’ve yet come up with a suitable alternative.

 

GDS publishes its new design for technical documentation

The Government Digital Service has been working on establishing a standard design for its technical (i.e. developer) documentation. This content is for systems architects, developers and users of the GOV.UK platforms and APIs.

You can see an example at: GOV.UK Platform as a Service

Gov.uk technical documentation

Cherryleaf was given a preview of the new design a few months ago, when we ran an API documentation training course at GDS. We made a couple of suggestions, which look like they’ve been included in the final design.

The documentation has these main sections:

  1. Overview. This includes why you would use it, and the pricing plan.
  2. Getting started. This includes prerequisites and limitations.
  3. How to deploy
  4. Troubleshooting
  5. Managing apps
  6. Managing people

Elsewhere on the website is information relating to support, the product features, and the product roadmap.

As with other GOV.UK content, the team carried out research into what developers wanted, and they carried out usability testing. I understand the researchers discovered developers preferred content to be on a long, single page, and that they would be working in a two screen environment. Using long pages enables users to search and navigate with the keyboard, rather than the mouse. GDS also looked at other developer websites, such as WorldPay and Stripe, for best practice.

GDS is highly regarded in the technical communications community for its excellent work on the GOV.UK website. This means it is likely other organisations will copy GDS’s design for their own developer documentation.

 

March dates: Advanced technical writing and new trends in technical communication training course

Discover the advanced new writing styles emerging in technical communication by attending Cherryleaf’s popular training course. Don’t get left behind: past clients include technical communicators from Citrix, GE, IBM UK, Lloyds Banking Group, Sage plc, Schlumberger, Tekla and Visa International.

The next public classroom course will be held on Wednesday 29th March 2017 at our training centre in central London (WC2R).

For overseas clients, we will hold a class live over the web (on 22nd and 23rd March), if there sufficient interest.

See:

Advanced technical writing & new trends in technical communication training

 

Writing documentation in an Industry 4.0 world

Industry 4.0 must be one of the “words of 2016′. We’re seeing a number of discussions on how this will impact on instructional design and User Assistance.

Ray Gallon has blogged on the question, what role should you have in machine-machine information?, exploring the differences between automatic, programmed dialogues, and non-programmed ones. Sarah O’Keefe has also blogged on the German initiative called iiRDS, the Intelligent Information Request and Delivery Standard.

It’s probably too early to form any firm conclusions on the impact Industry 4.0 will make, but it seems like some of the other trends we’ve highlighted this year are following a similar direction – documentation chatbots (docsbots), content as an API and treating documentation as code. There are similarities with iiRDS and APIs in looking at methods for content interchange, although it’s fair to ask, does the technical communication community need yet another standard?

Standards are like toothbrushes - we all know they're a good idea but we don't want to use somebody else's

Have Amazon, Dropbox, Microsoft and Google got their information design wrong?

On an API documentation course we ran for a client yesterday, we showed a number of developer documentation websites, including ones from Amazon, DropboxGoogle and Microsoft. One common theme the delegates noticed was these sites contained a in-page table of contents, or a set of related links, on the right hand set of the screen.

Dropbox API documentation page

You will often hear Information Designers talk about F shaped reading, and that the right edge of the screen is ignored by users. If you put content there, they say, it probably won’t be seen by the readers.

So have Amazon, Dropbox, Google and Microsoft all got it wrong, by using the right edge of the screen to provide navigation? Have the improvements in screen technology and the introduction of tablets and smartphones changed which areas of the screen users notice?

What do you think?

Towards content lakes

One of the trends in both data and content management is the move away from silos. In data management circles, there is a trend towards the collection and aggregation of customer data into “data lakes”. According to Margaret Rouse, a data lake is:

A storage repository that holds a vast amount of raw data in its native format until it is needed. While a hierarchical data warehouse stores data in files or folders, a data lake uses a flat architecture to store data. Each data element in a lake is assigned a unique identifier and tagged with a set of extended metadata tags. When a business question arises, the data lake can be queried for relevant data, and that smaller set of data can then be analyzed to help answer the question…Like big data, the term data lake is sometimes disparaged as being simply a marketing label for a product that supports Hadoop. Increasingly, however, the term is being accepted as a way to describe any large data pool in which the schema and data requirements are not defined until the data is queried.

(source: what is a data lake?)

“Content lake” isn’t a word that’s used in the content management or technical communication sectors yet, and whilst it seems unlikely end user content will grow at the same rate as other forms of data, there’s a fair chance this phrase could catch on.

A content lake is likely to have similar attributes to a data lake:

  • Content will be stored in a native format that is then changed into other formats.
  • It will use a flat architecture to store data.
  • Content will be stored in some type of structured format. Perhaps XML, JSON or plain text (with AsciiDoc-like attributes assigned to certain sections). However, user documentation does not require the rigorous structure of other forms of content.
  • The content lake can be queried for relevant content, and that a smaller set of information can then be extracted to help answer questions. This might not mean publishing content on-the-fly, but generating PDFs, CHM files and web-based content from a single source.
  • Rather than content being simply archived, it will deliver the right information in very short timeframes.

See also:

Please share your comments below.

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 “Update: The Internet of Things – creating a digital user guide to attach to a door”