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

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

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

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


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

Stack Overflow is moving into documentation (get the popcorn)

Stack Overflow, a collaboratively edited question and answer site for programmers, has announced its plans to add documentation to the site:

“Lately we’ve been asking ourselves “what else could we do to improve developers’ lives on the internet?”. Jeff’s original announcement of Stack Overflow said this:

There’s far too much great programming information trapped in forums, buried in online help, or hidden away in books that nobody buys any more. We’d like to unlock all that. Let’s create something that makes it easy to participate, and put it online in a form that is trivially easy to find.

Stack Overflow has made all of that a lot better, but there’s one area that is still hanging around: Documentation. Just like Q&A in 2008, Documentation in 2015 is something every developer needs regularly, and something that by most appearances stopped improving in 1996. We think, together, we can make it a lot better….

…We’re hoping we can improve documentation, not just move it under the domain.”

It will be fascinating to see how this project progresses – what issues they encounter, how they tackle these, and if the solutions work.

Continue reading