This post is part 1 of our Software Support and Artificial Intelligence series. You can find an overview of the 5 posts on our introduction post. If you are reading this before all posts have been published make sure to sign up for our AI & Docs mailing list, where we send notifications when we publish these posts and similar content.

Documentation is important and helps software products scale

Most people will agree that documentation is a critical component for any software product. There just never seems to be enough time/money to properly document everything (we are sometimes also guilty of this). On one-off projects, you can sometimes get away with this. But when you develop a product, insufficient documentation damages your software’s scalability.

I see 4 areas where documentation plays a critical role:
1. On-boarding and training: Typically, documentation will contain a “Getting Started Guide” that gives new customers the information they need to start using a product.
2. Problem solving: Self-service support: customers use documentation to find solutions for the problems they encounter with a product.
3. Feature adoption: Customers learn about new or previously unused features.
4. Pre-sales: In the digital age, customers evaluate a product based on its online documentation. Keyword rich documentation also helps customers find your product through search engines.

Documentation practices are under pressure

Several trends undermine documentation teams’ ability to deliver, especially for web applications:

  • Less funding for documentation teams: I've heard stories of documentation teams that get cut to 1/3 their size or worse. Cost cutting puts documentation teams under pressure from both sides: even as the headcount is reduced, expectations for self-service support might still be increasing.
  • Faster product development: Development cycles keep speeding up. Where development cycles used to take months, digital distribution channels and agile development practices opened the way for weekly or even daily deployments.
  • The customer’s shortening attention span: The average attention span of a customer is shortening. A barrage of distractions mean that customers have less cognitive space for your application. Customers expect support to work like a GPS: minimizing cognitive load, providing just enough information when they need it, in a format that is easy to consume.
  • Shorter interaction cycles between customer and documentarians: Email and instant messaging have made near-instant feedback possible and customers now also expect faster interactions. More and more, customers expect to have conversations with a product. A need is arising for reformatted documentation that can be used by chatbots, in order to deliver documentation as conversational snippets of information.
  • Gathering customer data to build better services? Companies collect vast amounts of information about their customers. While it is still early days, customers are beginning to expect that you know who they are and how they are using your products.

The manual is dead, long live the manual! The rise of embedded documentation.

All this means that the way we used to do documentation no longer suffices. We can’t rely on a book-publishing-like process to create our documentation: manuals are not enough. Our customers require more than a manual that they can consult when they are in trouble. Documentation that is embedded in an application does exactly this. Intelligent use of microcopy, pop-up help, walkthroughs, and help centers, make documentation more granular and address most of the above problems.



In my next posts I’ll explore how artificial intelligence could be used to anticipate documentation needs. I’ll argue that a combination of AI and embedded documentation could mimic natural teaching/support models.

Other posts in this series:
Part 2: The Helpful co-worker model
Part 3: Clippy: misunderstood brilliance before its time
Part 4: Repeating Clippy’s mistakes with Walkthroughs
Part 5: Automated proactive support as embedded messages



Interested in AI for Documentation? Sign up below and we’ll email you updates on our research.

Subscribe and get notifications about the next parts in these blog post series!

About the author

Kristof van Tomme

CEO, Co-founder

Kristof Van Tomme is an open source strategist and architect. He is the CEO and co-founder of Pronovix. He’s got a degree in bioengineering and is a regular speaker at conferences in the API, DevRel, and technical writing communities.