Internet of Things at stc17
This week I’m attending STC Summit 2017, the annual conference of the Society for Technical Communication. These are my notes from one of the sessions at the conference. All credit goes to the presenter, and any mistakes are mine.
The IoT (Internet of Things) is a hot topic, so I was keen to hear about documenting an IoT product. Michael Harvey presented a case study, “Documentation Support for an IoT Product”.
An Internet of Things is any collection of devices that contain electronics and software for collecting data and for sharing data amongst the devices. An IoT can generate a huge volume of data, in the form of continuously flowing events. Michael described the documentation for a product that developers use to process those events and data.
Michael works on SAS’s flagship product for the IoT. Michael’s session was about what he learned while working on this project, and how we can apply these principles on projects we work on.
What is the IoT
The term IoT was coined by Kevin Ashton. It started when he and his team linked RFID tags through the internet. Other people have built on this. Objects and devices send out signals, which are captured, analysed, and distributed over the internet.
Some use cases for the IoT:
- Sensors on oil wells showing oil extraction rates, temperature, pressure.
- Sensors on water meters, using for billing.
- Sensors on truck engines, for engine diagnostics and driver behaviour. This saves logistics companies a lot of money.
The frequency of activities could be 1000s of times per minutes, or much lower, depending on the use case.
The product Michael worked on was SAS Event Stream Processing (ESP) – a set of tools to build apps that process and analyse events, and can perform real-time analysis of that data.
Michael discussed some use cases for the ESP system
- Monitoring rogue trades on capital markets.
- Detecting fraud and analysing cyber security.
- And more.
Michael inherited an overview and a user’s guide. Just 2 documents.
The overview was very brief – just 1 line of text and 3 lines of code.
The user’s guide was a little unstructured, with every heading at the same level, and page after page of C++ code. That clued him in about who the “user” was. The language was a trifle convoluted.
Michael decided he was in a little over his head. He went looking for a graphic to give him a conceptual overview. It didn’t help much. The text on the diagram wasn’t consistent with the text in the manual. There was no indication of how events flowed into or out of the diagram.
The documentation and diagram didn’t tell a story. What do I do, what do I do first, then what, for what reason.
How did Michael tackle this problem?
- He spent a lot of time getting to know the docs – annotating the user’s guide and rationalising the use of terms, so that he could learn while writing.
- Then he scheduled time with the developers to resolve his questions.
One trick was to figure out who the audience was – it turned out to be both developers and people who use ESP systems to analyse data. Writing for developers is an art. They have little tolerance for documentation. Build on what they already know rather than repeating what they already know. You need to spend time with them to find that out. Developers skim documentation. So, use terms consistently, so they know what you’re talking about. Make sure you provide easily accessible reference material.
A challenge Michael had was that the product was in flight as he was writing the docs. He therefore had to continually revise the docs. He was also handling new material for a new XML modelling layer and user interface. He had to learn complex technical concepts, like connectors and adapters.
Learning how to read code is not easy, and is a bit boring. But it pays dividends. In particular, you can pull out snippets of code to put in the docs. He also became familiar with various technologies such as Yarn Ready (Hadoop) and Apache Camel. He needed to understand enough about these technologies to help ESP customers to use the technologies in the ESP context.
Michael emphasised the importance of differentiating between the roles of the engineers and the technical communicators. Both roles have equal value. Engineers leave gaps in docs, because they assume their readers know certain things. The tech communicator’s role is to overcome this “curse of knowledge”.
It’s important to build trust with the developers, by spending as much time as you can learning and studying, before you ask questions.
After all this work, Michael had the story for his documentation: Streaming data, events flowing through the product, these were the foundation of the rest of the docs. Michael discussed the nature of streaming data, how it differs from static data, the models that handle such data, and how the events flow through ESP. He was now able to improve the diagram giving a conceptual overview of the ESP system. He called it the event stream processing diagram v2.0. His diagram started showing up in educational materials, which was a clue he’d done a good job. Later, he improved the diagram even more.
A learning point is that tried and true tech writer techniques can be used to tackle any complicated technical material.
What’s next for the IoT
IoT is useful for precision agriculture, transport, airlines, healthcare, and the security industry.
Machine builders need to start thinking about themselves as information vendors. Their machines collect and share feedback from customers.
Thanks Michael for an interesting session about the IoT!