The importance of Process Documentation and Knowledge Transfer in organizations goes without saying; however, the documentation of Expert Knowledge is a time-consuming process with little to no advocating in organizations.
I had the opportunity to manage and be a part of a project to Imagine and create a better Process Documentation experience to help Knowledge managers and Technical writers Increase Authoring and Publishing efficiency.
Information regarding the company and its products has been omitted and obfuscated in this case study to comply with NDA.
Documentation,
A fragmented process
Problem #1: Process Documentation can become a siloed process when each branch of an organization would create its Knowledge Base: Flowcharts, Word files, PDF's, PowerPoint presentations. Those are all isolated and static documents.
Scattered information or duplicates can cause more damage than help If it's a pertinent Tech support information.
Problem #2: In the case of tech support, whether it’s software or a medical device, linear How-to-guide documentation is not enough, what if a user has multiple decisions or a condition to be met?
If Flowcharts are the industry standard for troubleshooting, why are they still being shared as printed manuals thousands of pages long or as an embedded image in a company wiki?
How might we improve the process of Authoring and Publishing
of Flowcharts?
My Role
I managed the project during the IBM accelerator which took place between October 2018 and February 2018. working with me was Alex our Head of R&D, David a Technical writer, and Noam Our CEO Product Owner.
Design Sprint Milestones
We could not tell how long would development take so if we could solve the design stage ASAP it would give more time for development.
I was able to secure 2 weeks for the design sprint, my concern was:
How are we going to test such a product?
Text editors could only be tested when they’re working, I had to get a working version of our initial design and so the prototype will have to be a live version in order to test and reiterate.
Brainstorming
Collaborating with IBM gave us access to Watson Discovery - AI document reader, and the power of text recognition played a major role in our initial ideas of the product.
- Using Watson to parse the text of work instructions and generate flowcharts.
- Run validation of flowchart and debug infinite loops or open-ended flows.
- Enable users to edit each step in the flowchart and attach visual aids such as Images or Technical illustrations, also add a more descriptive text.
- Integrate the Flowchart editor with our KMS to auto-generate Troubleshooting Guides using a flowchart information structure.
After refining those ideas we were able to recognize three main tasks our users will need to complete:
Authoring:
The user will be able to write down the process instead of drawing a diagram. During the authoring task, he can view the flowchart rendering and with the Watson discovery running in the background Validating the flowchart and notifying the user on ways to optimize his flowchart or resolve issues.
Populating:
Using the flowchart the user will be able to add additional descriptive information such as Paragraphs, Images, and Technical illustrations, in other words, a Mini CMS will be integrated.
Publishing:
After authoring and populating the flowchart with information the user would be able to publish the flowchart as an interactive step-by-step guide from the flowchart editor.
Competitive analysis
From the start, we had no doubt that the solution we were after was nothing new, the market is teeming with documentation tools, flowchart editors such as Draw.io, Lucid chart, and Microsoft Visio among others were well-crafted products.
Although these products didn’t provide their users with publishing and validating functionalities they were nonetheless the industry standard tools with millions of users so if there’s a place for a good reference of what good diagramming tools look like it’s these products.
Early Sketches and Wireframes
I started sketching out a layout which will facilitate the three main tasks And after it was approved I quickly knocked out some wireframes for different scenarios.
My reference was the layout of a programming IDE (Independent Development Environment), such layout usually facilitates similar activities and is very flexible when it comes to multipanel view and typographic hierarchy.
Quick sketches were made and analyzed before we proceeded.
Readymade solutions
Planning for this sprint I knew we needed to use existing solutions to accelerate the development and so after searching for open source libraries our Head of R&D recommended to go with these:
A versatile text editor implemented in JavaScript for the browser.
A flow & process orientated diagramming library inspired by Blender, Labview and Unreal engine.
These libraries could save us precious time in UI development.
Testing usability
Alex was able to release an early version so we could test it internally, this version allowed me to validate my design decisions in terms of usability.
Since the authoring task would take the longest time to complete for the user, testing the interactions of the text editor at an early stage helped us discover what were the must-have features and the nice-to-have specifically for the Syntax editor.
What did we accomplish?
Syntax Editor:
After configuring the CodeMirror library we were able to implement our own syntax.
We designed the syntax to be as simple as possible, the Watson Discovery will compile the text to flowchart structure.
Flowchart View:
This view helps the user to get an overview of the entire flowchart, but most importantly the user can edit his flowchart based on visual context and error messages will appear in place on the exact node.
Step Editor:
After the user finished writing the flowchart he can continue adding supportive content such as Images and descriptive text to further elaborate on each step.In the Step editor, the user will also be able to control the layout of which the content will be presented in the end-user mobile app.
The version we had at the end of the design sprint although not stable enough but still a version that could be improved and tested, this gives us 3.5 months of marginal time to finesse the flowchart editor more, Fantastic!