Which type of platform is best for developer documentation?

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.

SankeyTextualVariant: Visualisation software for comparing texts

Professor Martin Paul Eve of Birkbeck College, University of London, has released, for free, the visualisation software that helped him compare the texts of the novel Cloud Atlas. It displays the differences as a Sankey diagram. It’s intended to be used for comparing contemporary fiction, but it may have uses for analysing other long documents.



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”

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 “The Internet of Things – creating a user guide for a fridge door”

Perfecting collaborative authoring for online Help

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.

Continue reading “Perfecting collaborative authoring for online Help”

Cutting and pasting content into Word documents – Is there a better 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.

Continue reading “Cutting and pasting content into Word documents – Is there a better way?”