- What: Documentation Support for an IoT Product, A Case Study
- When: February 16, 2017
By Nupoor Jalindre, Student and Chapter Member
The Internet of Things (IoT) is emerging as an unprecedented opportunity for many players in the communications, information technology, and consumer electronics industries. Definitions of ‘IoT’, application scopes and growth forecasts strongly diverge with some analysts estimating the number of connected devices by 2020 to be around 20 billion. Smart, connected devices are already transforming our world and the competitive forces in business. To demonstrate the impact it will have on our content strategy and lives, Michael Harvey, in this month’s session, spoke about his own experience in developing and delivering documentation for an IoT product from its inception.
Michael Harvey, STC fellow and former President of the STC Carolina chapter, works as a Principal Technical Writer at SAS providing documentation support for SAS Event Stream Processing (ESP) since 2013. Michael gave an overview of Internet of things with interesting examples, use cases and further led the discussion to ESP and and how it fits in the IoT. The strategies and skills discussed in the session will certainly be useful for not just writers entering into the IoT field but for others who can draw upon techniques to build content from scratch.
Event Stream Processing (ESP) in the IoTESP is a set of programming tools to build applications that process and analyze streaming data which can perform real-time analytics on that data. An example use case is an application in capital market trading systems used to detect trading patterns and avoid frauds. ESP is SAS’ flagship product providing sensor data monitoring and management over the internet for edge systems.
Evolution of the ESP documentation setMichael discussed his journey in building ESP documentation which started with a single User’s Guide with many pages of code and problematic content organization. Many new terms were used throughout the guide which had no definitions and the graphics were not intuitive. The process of revamping the entire documentation began with annotating the User’s guide to reduce complexity of information. He investigated terms exploring their own definitions along with their relevant context. Asking pointed questions can help eliminate unnecessary and redundant content to make concise topics.
Steps for writingMichael discussed the following steps to achieve successful completion of documentation process for IoT products:
- Learn while writing
Educate yourself by annotating, defining and asking questions.
- Who is the audience?
Analyze audience whether they are programmers, end users or both.
- Write for programmers
Balance amount of information building it on the context, flow and information that they already know.
- Build the plane during takeoff
Develop information while the new product is being built. Repeating the steps: learn, question and understand while writing and revising generated content constantly is the key to be able to deliver on time.
- Build trust with development
To be able to do the aforementioned tasks, it is important to build a good working relationship with developers by asking the right questions, meeting with them whenever possible and never complaining about the amount of work.
- Sweat the technical details
Learn to use new technology which is used in the product to ease understanding.
Missed the meeting?View the event recording on Vimeo.
Nupoor can be reached at nsjalind at ncsu dot edu.