Documentation made easy for AI and Data Science

Some projects look simple, yet, when the legacy issues show up, the caveats in the product documentation are visible and also reflect gaps in the user experience.

We recently encountered a SaaS-based product documentation with similar issues. The product is exceptionally good with the objective to connect multiple virtual databases and analyze them simultaneously in real-time. Considering the minimal understanding of novice users, a strong user interface is provided to handle technically complex activities in a simpler way. It also gets rid of traditional time-consuming methods to bring the data to the application.

Our client – Zetaris was facing a huge challenge due to inconsistent documentation comprising of legacy issues like inconsistency in naming convention, workflow-based content flow, and standard documentation practice. The documentation was not comprehensive and consistent enough to help and educate the end users of the product. In addition, the language did not meet the industry standards. Due to these reasons, the documentation came out to be ambiguous and incomplete to the customers.

Therefore, we initiated the project by identifying the key problems that created limitations from the documentation usability perspective:

Key ChallengesDescription
Feature Information Documents had incomplete information that led to inappropriate knowledge development.
Scope of end-user documents No information segregation for meeting different requirements of end users (technical and non-technical).
Terminology and UIInconsistent terminology, naming conventions, and treatment to the abbreviations across the document was observed that eventually led to end user opacity. 
Language and GrammarLong, complex, and incomplete sentences with inconsistent voice, tonality, and adherence to grammar rules.
Legacy issuesThe content was out of context with respect to the product.
Visual Appearance The visual appearance was not appealing in terms of content organization and format.

How did we solve these challenges?

After identifying the challenges, we began by bridging the information gaps observed in the documents. Our team started documenting the undocumented features.

Our Approach:

  • Analysis of existing content
  • Plan the new content structure/ design
  • Standardize the terminologies
  • Edit legacy content
  • Baseline the new content

While bridging the gaps, for both technical and non-technical users, we suggested individual guides to meet their respective requirements. So, we started with a Quick-Start guide that would help the onboarding process. We also helped them identify and prepare other technical documents that would best suit their organizational goals.

Existing Content Analysis

In this phase, we performed a detailed analysis of existing content to check structure, information gaps, and other inconsistencies and flagged our findings. We followed the simple approaches like:

  • Content Structure Analysis – We analyzed the existing content structure and checked for navigation issues within the content, information layout (if the content context was in sync). We also analyzed the content flow in correspondence to the application workflow.
  • Information Gap  Analysis – We analyzed terminologies, UI content, and feature definitions for obsoletism and inconsistency with the UI. In this approach, we also observed that UI elements were not in line with the industry standards.
  • Consistency Analysis – We analyzed inconsistency in information formatting, screenshots added to the documents, and their relevance to the presented information context. 

New Content Design Approach

Based on the audience needs understood by the SMEs during various discussions, we proposed a content design approach. We worked on the re-structure and design of the information presented. It also included identifying different types of documents that would be required by product users. 

Structure – We worked, firstly, on identifying different documents to meet certain purposes like the Quick Start Guide for onboarding and the Comprehensive Guide for assisting the users with performing actual tasks using the fullest potential of the product. The structure was prepared and presented for individual documents. 

Design – We worked on the design of the information presentation adhering to a style guide. We also organized the information flow to best match the information requirements of end-users.

Standardize Terminologies

Inconsistencies related to the abbreviations and terminologies observed during the analysis phase were discussed with the client and then an approach was decided on how to structure and present the content that elaborates abbreviations. Considering a wide range of audiences from a limited understanding of technology to expert level, a structure and design to present terms and their definitions was also prepared.

Structure – How the abbreviations to be elaborated and terms to be described based on audience need was prepared.

Design – Presenting the information and connecting it with the main text without breaking the information flow was designed. 

Editing legacy content

The legacy content was edited to match the scope of the features and screenshots were updated to match the UI of the last release. Any information gaps identified during analysis were bridged while editing the content to match the product as per the last release.

Baseline new content

After performing all the above-mentioned activities, the content was baselined and made ready for updating as per the product release in progress. With regular interaction with the SMEs, the content for the enhanced and new features was drafted and the baselined documents were updated.

Conclusion

This entire project was authored using the tool Wiki Confluence. Our domain knowledge and rich experience in technical writing were leveraged to help solve the challenges mentioned. We worked with the client to understand the requirements and offered suggestions based on our industry experience and expertise.

Our solutions covered detailed information backed with screenshots to make the product documentation user-friendly. With our bandwidth, we were able to get going with the deliverables in a short time. The Quick Start Guide was appreciated by the clients due to its quality standards. Thereafter, we continued to follow the same strategy to meet the set standards for other documents.

What can we do for you?

Our team has rich experience in meeting every technical writing need, such as content mapping, content migration from unstructured-to-structured, technical documentation, etc. With our bandwidth, we can meet any requirement and deliver premium technical writing services in a comparatively shorter span of time. For any queries, contact our team. You can also explore our services on our website

Leave a Reply