The ROI of writing documentation for your software startup

The ROI of writing documentation for your software startup

I should probably start by saying that if you work in a field that is regulated by law to have comprehensive documentation, then I don't really know anything about your field and you should take what I write here with a serious grain of salt.

How does a start-up ever decide to say "We need some documentation for this?"

A couple of scenarios come to mind :

  1. "Shit, I wonder if anyone will get this. Eh, we'll..."

2. "Hm, maybe not everyone learns watching videos. Maybe we'll..."

3. "I'm going to lose my mind if we have to onboard every user on this manually. Maybe we should..."

"...write some documentation for this."

They can be simplified, in order, in:

  1. Documentation as a crutch
  2. Documentation as an alternative learning tool
  3. Documentation as a cost saving tool

<h1> Documentation as a crutch </h1>

It uses documentation as a required thing to read in order for the product to be fully understood.

It's as much part of the product as the "Login" button for a full user experience.

It becomes even more dangerous when the need for it comes at a validation stage, pre-revenue as it can not only hide UI problems, but overall product vision ones.

How do you know if your solution is focused enough if a user needs a bunch of docs to understand how you solve their problem?

In terms of user acquisition, can there be a scenario where a user would rather stick to the workarounds rather than spend time onboarding with your documentation?

My dad, for example, still wants to get out of the house, get a bus and spend 40 minutes paying his bills in person because he finds the small print on online payments confusing and not trustworthy.

The fact that the people who built the site didn’t care enough to make things obvious—and easy—can erode our confidence in the site and the organization behind it. -Steve Krug in Don't Make Me Think

There is, however, a place where it makes sense to provide documentation as a crutch.

Power users.

Maybe there are features that a small segment of your users get a lot of value from, and adding that to the general UX may create too much noise for your regular user. Otherwise, bringing less used features upfront could lead to feature bloat.

The accumulation of features, although useful for a certain number of users that are technologically adept, simply increases the likelihood of errors for most users. Thus, “not all features are equally valuable” (Anton & Potts, 2000, p.1). A new feature may produce a marginal functionality gain but a widespread usability loss (Bishop, 2008).

In summary:


  • Can help you navigate tricky UI when you are constrained in time and need to get something out
  • Good for power users to make use complicated functionalities that can't be simplified any further without losing quality


  • Really annoys the user
  • Provides an easy fall back from doing the hard work of thinking about user experience
  • Can easily help you bloat the product with features because you can always fall back on documentation

<h1> Documentation as an alternative learning tool </h1>

Some people learn using numbers, some using metaphors, drawings, little songs and so on.

I read in an old book (name slips now) that the way we've been teaching different disciplines only helps propagate the learning style that worked for those that got good at it. Which is great for the top performers, but disastrous for those that are not intuitively good at it from the get go.

For example, if you are a math person and you've got an intuition for numbers, you're most likely to have the same learning style as your favourite teachers. When you get to teach math to someone else, you're going to use that specific style, and those who seem to have some talent for math will get it easy and so on. What about the kids that learn better using drawings?

That being said, if we use the metaphor above, you are aiming for the segment of the audience that gets it upfront either way. There is an argument that if the user doesn't get it, maybe there are not your users.

I don't particularly subscribe to the view above in startups that don't have a solid product-market fit, but it's highly dependant on the investment that you are making in building the documentation.

Maybe you'll spend 30 days building documentation to find that no one wants it, or 3 days to write an article that reveals that your adoption rate increased because your particular user segment is more likely to use written documentation as a primary learning method. As a startup, you can always find out new things about your users, and those things can turn into a competitive advantage especially if other companies don't know it yet.

The same way someone who has an online course may provide a video, slides, transcription and a audio file, consider testing the need by offering some documentation for your audience and tracking the usage. Never at the expense of allowing the user to understand the product without it.


  • Helps with audiences that don't use the same learning style


  • Adopting this "all angle" teaching style can turn into a time black hole and you might be stuck creating "<your brand> + academy" rather than developing the real product

<h1> Documentation as a cost saving tool </h1>

Onboarding can get expensive, especially if you're playing in the B2B area. Contracts are usually more valuable so the individual attention per client is higher.

However, before thinking that it can save you thousands of meetings, I wouldn't transition the whole customer experience to some sort of funnel yet.

How much of the whole customer experience can you delegate to this documentation? I don't know, and you probably don't either.

As a start-up, I would consider customer support as pure gold. Doing hands-on customer support that doesn't scale right now is exactly the thing that has potential to give you some great insight. You can't ask questions back to the client when they read your documentation, you can't see their faces, their reactions, where they hesitate.

Consider using the product documentation as a follow-up after you did your customer support sessions.

I would be as judgemental with investing time in product documentation as much as I would be if we were to build a new feature. If it's a product meant to save costs, it should be judged by those metrics and not feel like a debt that you owe your users.

It's a living document that requires maintenance and therefore time spent on it could be spent somewhere else if the business doesn't get a return on the investment. Test, test, test.


  • Saves time onboarding clients
  • Saves time banging on the desk repeating the same thing over and over


  • You can lose really valuable insight about your product and the chance to form strong relationships with your clients

General advice on writing your documentation

  • Speak human. The only thing worse that having to read through War and Peace to understand a product is making sure the user can't understand one sentence. How do you do that? Record yourself onboarding a client through the platform. Transcribe it, format it, publish it.

Here's some things people have been complaining about documentation:

Smart, et al. (2001) found through their interview study that there were negative perceptions about manuals, both printed and online, and problems with using them. Problems included: it was unclear where to find information; not enough or irrelevant information; application specific conventions made accessing information difficult; documentation made incorrect assumptions about what users knew; structure and layout made navigation difficult, especially in online help; poor or misused metaphors were confusing; and the documentation used inconsistent or confusing terminology.
  • Structure it so you can provide laser-focused solutions rather than create a 100 page novel. I should be able to understand the context without having to read from the beginning. Can I jump in and out really quick if I already know what I want to solve?

Consider writing for people that need to do things vs. people that want to learn things. A lot of your users are not there for a picnic and a book, they are there to finish some work.

Sullivan & Flower (1986) conducted an early study using observation of six participants who conducted real tasks with manuals and computer systems combined with concurrent verbal protocol. Their study showed that users do not read the whole manual, or any section in its entirety, instead they stop using it once they have found enough basic information to begin the task and would rather reason out the task than follow involved instructions. No-one read the manual carefully, most began to read the screen before the manual, only using it to answer questions when they failed.
  • Treat it as a place where people come voluntarily, because that's the way they want to learn.
  • Beware of the metrics. People accessing the documentation could mean that your UI sucks and/or people ar valuing the documentation. This is not something that I know how to solve yet. How many people are accessing the documentation because they want to vs. because they don't understand the product vs. because contacting customer support is a pain in the ass and they need the answer now?
For computer systems, print or online help is seen as a last resort (Rettig, 1991), after repeating steps, rebooting and asking coworkers for help. Brockman suggested that reasons for this included that adults are impatient learners who rarely read instructions fully, are best motivated by exploration and learn from mistakes. They are intimidated by large manuals full of detailed tasks (Brockman, 1990).
  • Try and play with different media formats. Product documentation is, in the end, a compressed way of transferring knowledge.  Through documentation, you are taking someone's experience with the product, compressing it into written form, decompressing it again on the user's side and into the user's brain. Try and see which medium offers the best way of getting information across in a lossless format without frying your brain. Product-tours? Images? Videos? Which one works best for your customer? I have no idea.
Use of the manual and use of all features are linked – for many products it is very difficult to know about or know how to use all the features without at least some help from the manual. Therefore the issues that people have with manuals limit their use of features and those feeling overwhelmed by over-featuring may be uninclined to access the manual in order to learn more. Therefore a vicious cycle is likely to be created, which is ultimately detrimental to the users who are not getting full utility from their products, and are experiencing negative emotions in relation to them. Improving interfaces by reducing excess features and improving other aspects of usability should lead to happier users who are satisfied that the interface is more self-explanatory and they do not have as much need to access the manuals.

Further reading:

Show Comments