---
title: "Tech comm trends: Providing value as a generalist in a sea of specialists (Part IV)"
date: 2018-10-02
description: "Identifying where the problems are Doc feedback buttons Surveys at select milestone events Summaries of weekly issues resolved <a href="
canonical_url: https://idratherbewriting.com/2018/10/02/providing-value-as-generalists-in-specialist-contexts-part-4/
---
# Tech comm trends: Providing value as a generalist in a sea of specialists (Part IV)
Some academic research indicates that identifying gaps and errors in docs can be one of the main contributions generalists can make. In an article titled [How API Documentation Fails](https://ieeexplore.ieee.org/document/7140676/) (published in [IEEE Software](https://ieeexplore.ieee.org)), authors Martin Robillard and Gias Uddin surveyed developers to find out why API docs failed for users. They found that most of the shortcomings were related to content, such as information that is incomplete, inaccurate, missing, ambiguous, fragmented content, etc. They summarized their findings in this chart:

[![Reasons why docs fail for developers](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/whyapidocsfail.png)](https://ieeexplore.ieee.org/document/7140676/)

The problem, they explain, is that the very people who can fix this content are usually fully engaged in development work. Robillard and Uddin write:

> Perhaps unsurprisingly, the biggest problems with API documentation were also the ones requiring the most technical expertise to solve. Completing, clarifying, and correcting documentation require deep, authoritative knowledge of the API’s implementation. This makes accomplishing these tasks difficult for non-developers or recent contributors to a project.
> 
> So, how can we improve API documentation if the only people who can accomplish this task are too busy to do it or are working on tasks that have been given a higher priority? One potential way forward is to develop recommendation systems that can reduce as much of the administrative overhead of documentation writing as possible, letting experts focus exclusively on the value-producing part of the task. As Barthélémy Dagenais and Martin Robillard discovered, a main challenge for evolving API documentation is identifying where a document needs to be updated.

In other words, simply identifying the gaps in the documentation can provide a huge value for the engineering team. There are potentially hundreds of pages of documentation. How do you know where the problems are, where users are getting stuck, where steps are missing or inaccurate? In short, how do you identify the problems in the content based on the user experience?