At the Write The Docs event in London last night, Gergely Imreh presented Resin.io’s approach to customer-driven docs – documentation as self service support. Resin.io is a software company that provides Linux containers to the Internet of Things. It sees itself as a support-driven organisation, and so documentation is very important to them.
The discussions at the end of the talk were around which type of platform is best for developer documentation.
Resin.io uses an in-house system, based on Markdown and a flat-file publishing tool. They build pages from “partials” (snippets of re-usable chunks of information) to create “parametric information”. Pages can be built to match different criteria. For example, using Resin.io on a Raspberry Pi and Node.js. It provides an authoring environment that is easy for developers to use; it doesn’t require a database-driven CMS; and the content can be treated in a similar way to the code. The challenge with this type of system is getting it to scale. The “intelligence” of the system is through storing content in folders and using scripts within pages. As the grows, they are finding it harder to manage.
Gergely said he’d like see if a wiki-based system would work better. Content would be easier to edit, as pages would be more self-contained.
Kristof van Tomme suggested using a database-driven CMS. Pages would be built “on the fly”, by the CMS. In this situation, the “intelligence” of the system is through metadata wrapped around each topic and the database software that’s managing the content. The downside is it can mean there might be challenges in moving it to another platform at some stage in the future. You also have to manage the database and protect the CMS from potential hacking.
Another suggestion was to use a semantic language to write the content. This could be AsciiDoc or DITA. In this situation, the “intelligence” is placed in the topics and with the writers: they “markup” sentences or paragraphs for each applicable parameter, such as audience and computer. These can be published as flat files or be managed by a database. This approach is scalable and tools-independent, but it requires much more work by the writers.
What’s best depends partly on your view of the problem. Is it a information design problem, a software problem, or a data management problem? There are pros and cons to each approach.
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.
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
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:
- Overview. This includes why you would use it, and the pricing plan.
- Getting started. This includes prerequisites and limitations.
- How to deploy
- Managing apps
- 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.
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.
Advanced technical writing & new trends in technical communication training
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?
On an API documentation course we ran for a client yesterday, we showed a number of developer documentation websites, including ones from Amazon, Dropbox, Google 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.
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?
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.
Please share your comments below.
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.