More and more startups and enterprises are recognizing the importance of high quality product documentation, but it’s tough to know where to start. I’ve taken a few enterprise software products from “nothing to something” documentation and this is the framework I’ve built for myself to create MVD—minimum viable documentation.

If you’re a technical writer trying to find your footing, or someone who cares about adding user documentation for your software but have no idea where to start, this is the guide for you.

What is minimum viable documentation? #

If documentation is a product (and it is), minimum viable documentation is the bare minimum documentation that is useful and helpful to customers.

Something good is better than something chaotic and unhelpful, and it’s much better than no documentation at all. It’s also easier to focus on getting to minimum viable documentation rather than trying to reach full-featured documentation as soon as possible, because you’re a human with a life that is not your job.

You might be working with a fully-functional software product that has no useful documentation. In that case, getting to full-featured documentation isn’t your primary goal—getting to minimum useful documentation is. So let’s get started.

Define minimum viable documentation for your product #

Before you can write MVD, you need to define what it is for your product. MVD differs depending on your market, customer base, product type, your pricing structure, and more.

I recommend you do the following to define what MVD looks like for your product.

1. Talk to your colleagues #

Your goal with these conversations is to get a good understanding of who the target user is for your product and the goals they want to accomplish with your product.

If you have product management, start with them. Find out as much as you can about why the product is being built, who it’s for, and how the product is being positioned in the market.

Also talk to engineering management or senior engineering subject matter experts (SMEs). What user problems are the software trying to solve? What level of expertise do the engineers assume the user has?

If you’re lucky enough to have a sales or marketing team, talk to them. Because of their efforts defining the customer journey, they can help you understand who the audience is and what the key success workflows look like. Who is the product targeting? Why do they want to use this product? What problems are they trying to solve?

Talk to the user experience designers to get an understanding of the user personas they’re designing for and what workflows they think have the most friction. You can also get a sense for how the team approaches their role, whether they’re more focused on designing friction-free workflows or pixel-perfect screens.

After talking to PM, EM, UX, and marketing, you can do the following:

• Identify what level of expertise a typical product user has, both with the domain and with the product. This functions as your audience definition.
• Write down the main goals of a user before and after they start using your product. What motivates the user?
• Map out the key workflows that a user is going to perform in the product. What tasks are the user trying to accomplish?

2. Perform a documentation competitor review #

It’s always a good idea to know what your competitors are doing! If you’re not sure what products your product is competing with, ask your sales or marketing people for a list or do some research on your own.

Pick 3-5 companies to focus on, such as your strongest competitors in terms of funding, usage, or closeness to what your product does.

You also want to make sure you’re not benchmarking off useless garbage when you perform your competitor review. In addition to the 3-5 competitors you identify, pick a couple industry leaders or companies that your colleagues mention as having good documentation, such as Stripe API docs, Microsoft docs, or even IBM docs, and include one or two of them in your competitor analysis.

The advantage of choosing the documentation of a couple larger products to review is that they tend to have established documentation teams and offerings in a variety of markets. This makes it easier to find a product that is well-documented and at least somewhat adjacent to what your product does.

The goal of your competitor analysis is to identify how the companies provide documentation about their product(s). Pay attention to the following:

• How is the documentation structured?
  • By feature?
  • By use case?
  • By persona?
• What documentation is provided?
  • What workflows are covered?
  • What seems left out?
• What type of documentation is it?
  • Lots of conceptual information about how the product works?
  • Heavy reference information but light on the how-to tasks?
• Who is the documentation targeting?
  • Look for introductory content or tutorials
  • Is there advanced developer content?
• How is the documentation site built?
  • Use the inspect element option in your web browser or a site like https://builtwith.com/ to figure out what technology the documentation site is built with.
• Anything else interesting?
  • Does a company have an interesting way of differentiating beta functionality?
  • Are code samples hidden behind toggle-to-expand options?
  • Is there a plethora of gifs, videos, or other multimedia in the documentation?

Document your findings, of course, and feel free to share your findings with your team during a demo. After all, they might be wondering what you’re doing if you haven’t started writing yet.

3. Assess the current state of your documentation #

If there is any sort of documentation for your product, you want to know what it is. It might be a sad README and some code comments, it might be detailed multilayered documentation without much organization or clear goals.

To get a sense of the current state, I recommend doing the following:

• Audit the existing content. Identify which topics are covered in the documentation already, and where. Make a list, and also keep track of what topics seem to have a lot of detail, and what you suspect might be outdated. This is a cursory audit, not an in-depth one that you might perform if you were migrating content.
• Look at the documentation analytics. If you have analytics for the documentation site, take note of which pages are most frequently viewed, which pages might be serving as entry points, and how much time people spend on various pages.
• Talk to your team and get their thoughts on the current documentation. Who has been writing it so far? Are they attached to any topics in particular? Do they share specific topics with customers regularly?
• Interview customers of the product and documentation to see what they want to see or find most useful today.

Depending on the quality of the existing documentation, these steps might not be that helpful in informing your approach, but help you set benchmarks for documentation growth and quality, plus identify links you likely don’t want to break.

If you don’t have any documentation, still talk to your team and customers. If you can’t talk to customers for some reason, you can look for discussions about the product on social media like Reddit, Twitter, or Hacker News to identify themes that people ask questions about or really enjoy about your product.

A brief note about terminology: As you review competitor and existing documentation and interview internal and external folks, you might find that your product has some inconsistent terminology. At this stage, you might want to delay the writing process while you create a definitive list of terms to use for the product. This type of work can take more time upfront but it’s easier to create consistency from the beginning than to apply it after the fact.

Define the structure of your documentation #

Before you start writing, you want to create a structure or a framework to place your topics into.

The structure for your MVD is directly informed by the work you did to define what MVD looks like for your product, plus some information-architecture-specific research.

• Revisit your conversations with colleagues. What workflows and functionality might be important to highlight? Who is buying your product? Who is using your product?
• Refer to your competitor review notes. How did your competitors and benchmark docs structure their documentation?
• Research information architecture best practices. Refer to some key articles from the Nielsen Norman Group, as well as the book How to Make Sense of Any Mess by Abby Covert, and the associated worksheets.

After this research, draft up some chapter headings and possible topic titles to start with, then get feedback from your UX, PM, Engineering, and Sales and Marketing folks. How accurate, relevant, or helpful does the new structure seem? Have you made any assumptions that don’t make sense for the customer base?

Expect this information architecture to change as you write the MVD and especially as you develop full-featured documentation. This is the nature of a minimum viable product! Put a task in your backlog to plan to refine the structure after you finish MVD and are approaching full-featured documentation so that you can iterate without confusing your customers with frequent changes, and plan so that you don’t break any links.

After you design the initial information architecture, you can start writing.

Start writing minimum viable documentation #

So you know what minimum viable documentation might look for for your product, but how do you get there? MVD is all about creating useful content for your users, so start with the entry content!

Focus on key information for customers #

As with any “minimum viable” approach, you’re trying to get a basic functional framework down before you start improving it. As you lay that framework, be mindful of scope creep.

Think back to the key workflows that you mapped out earlier. Broadly cover the top few workflows and then flesh out details as you get more comfortable with the product and understand the user goals better. Why go broad instead of going deep into a specific workflow? You’re still learning what the customer finds useful, and what level of detail they might want or need about a specific workflow.

If you spend a lot of time writing a highly detailed workflow that you thought was important and it turns out it’s actually pretty intuitive for customers—that’s time that you could have used to write about something that was really confusing and holding back customers from succeeding with your product.

It’s likely that you’ll encounter cases and situations that you want to write more about. That’s great! Write them down and put them in a backlog to address later. For now, you want to stay focused on these minimal workflows to build out the minimum viable documentation for your product. You can get fancy with use cases and in-depth examples later.

Identify the simplest path to success #

Within those broad key workflows, start with the simplest path to success, the “happy path” that most of your customers will take.

That might involve writing a series of topics like:

• “Get started using Best Product Ever”
• “Install Best Product Ever”
• “Set up Best Product Ever”
• “Accomplish Straightforward Task in Best Product Ever”.

Get those written, reviewed, and published and start helping people use your product that much sooner.

Clarify any complexity #

After you write the documentation to support the simple path to success, what do you write next? Documentation that unravels where complexity lurks in your product.

Depending on your product familiarity, you might need to take more time to research and lean on technical subject matter experts (SMEs) a bit more to write this, but it’s worth it. This documentation content might be topics like:

• “Configure the Weird Setting You Must Touch”
• “All About This Task That Everyone Wants to Do but No One Can Find”.

You don’t want to get bogged down in documenting around product complexity here. Stay focused on the complex aspects of the key customer workflows, and the crucial information customers need. What might confuse someone if you left it out? What assumptions have you been making about the user that need to be made explicit?

This is often the step when I remember to write things like software requirements, role-based restrictions to functionality, or other crucial cases that are often assumed when developers write their own documentation.

Get feedback and iterate #

I assume you’re focusing on minimum viable documentation because you have more work than you have time to complete it. That’s why it’s important to iterate. Yes, I just harped on the importance of prioritization and focus—and it’s essential to make sure that what you prioritize and focus on is still important.

Check in with product management and engineering management regularly (I’d recommend weekly for an every-few-months or less release cadence) about what you’re prioritizing and why.

This check-in is mostly about getting signoff and validation, not direction—but don’t ignore the direction that PM and EM can offer you! If there are important releases coming up that will affect one of the key workflows on your list, you might want to document that workflow sooner, or in more detail than you might otherwise for MVD.

Use these conversations as a way of discovering what customers are paying attention to, and what your PM and engineers are paying attention to as well.

As you send your documentation out for technical review, you might also get feedback that you can use to improve your approach to MVD. With any luck, much of the feedback will duplicate what you have planned—and that’s helpful validation for your approach.

You might get so much feedback that you have to dump a lot of ideas into “plans to write this later” and a backlog that feels like it’s spiralling out of control, but if you stay focused on your scope, you’ll get to that backlog sooner and with a more comprehensive understanding of your documentation and your customers.

If the direction and feedback you get from your team is pretty far removed from your approach to MVD, it’s helpful to discuss why that might be and treat it as prioritization guidance for your future plans. Maybe you misunderstood a key target customer, or the purpose of the product in the market. You might discover you need to realign your understanding and vision of the documentation with that of your team.

What’s next after MVD? #

When do you know that you’ve reached minimum viable documentation? It’s somewhat of a fuzzy line. When you notice that you’re writing documentation by adding to existing topics, or writing net new example content, or documenting new features instead of existing features — you’ve moved past MVD and into shaping full-featured documentation.

As you start shifting into that mode, you’re no longer focused on creating the skeleton structure to build off of, but filling in the details and settling into the usual work of modern technical writing.

1. Go through the backlog #

Start going through your backlog of ideas. Revisit those ideas and group similar ones together, adding audience definitions, acceptance criteria, and learning objectives where you can. Note who the technical SMEs are and whether any upcoming releases are relevant for some of the tasks.

Ideally, you’re storing this backlog in the same spot as your engineering backlog so that your work is visible to the engineering team.

Work with PM or EM to prioritize those tasks and start working through them. As any writer for a fast-paced development team knows as well, the product development often happens faster than you can write about it, so you’ll never run out of tasks in your backlog.

2. Suggest product improvements #

As you went through a flurry of documentation writing to produce MVD, you likely identified some parts of the product that might need to be improved. Again, work with your PM and engineering teams to discuss possible product improvements.

You can also suggest product improvements that directly involve the docs, doing a review of UI text in the product, or auditing pages in the product to suggest opportunities for in-app documentation or context-sensitive help. This is a great opportunity to partner with the UX team as well.

Partner with your engineering and UX teams to make suggestions and build those relationships based on your newfound product and customer expertise.

3. Write use cases and examples #

To create more useful content for your customers, you probably want to flesh out specific example scenarios for using your product. You might have written some already as quick start use cases for getting started with your product, but you likely want to write more for the next stage of customer product understanding.

You can use example content to describe customization options for the product, or highlight domain-specific use cases for a market that your customer might be trying to break into.

4. Ask for feedback #

You put all this effort into creating minimum viable documentation, but how viable is it really?

Ask your technical SMEs, sales and marketing teams, customers, really anyone that might interact with the documentation internally or externally if they have feedback on your documentation improvements and information architecture.

You could perform some tree testing with the MVD structure to see if there are some improvements you can make to the information architecture as you flesh out the documentation, or just have short conversations with stakeholders.

Use the feedback you get to help shape priorities for your backlog. However, don’t treat all feedback you get as tasks that you must perform—if someone asked for it, it must be important, right?

Instead, validate feedback against your target audience definitions and user goals. Sometimes you’ll get feedback relevant only to a specific edge case that doesn’t make sense to document in the official documentation, or feedback related to a product bug that isn’t something necessarily appropriate to address in the documentation.

5. Review analytics #

Review documentation site analytics. Analytics are an imperfect source of feedback, but as long as you established a prior benchmark, check to see if the entry-level pages that you created or updated are the most popular pages.

• Are the pageviews higher, or at least somewhat proportional to the user base of your product?
• Are there any surprising outlier pages that have a lot of views that you might want to focus on?
• What search terms are popular?

You can use these to inform your plans and priorities.

Get from nothing to something with MVD #

It can be intimidating to create a set of documentation for a product from scratch, but I hope this post outlines a basic approach that can help.

Start by defining what MVD looks like for your product by talking to colleagues, performing a competitor review, and assessing the current state of documentation. Then do some additional research and define the initial structure of your documentation.

After you’ve laid the groundwork, start writing. Focus on key information for customers and identify the simplest path to success. Clarify any product and task complexity, and seek out feedback. Regularly make changes to what you’ve written as you learn more about the product and your customers.

As you evolve beyond MVD to full-featured documentation, work through your backlog, suggest product improvements, write use cases and examples, and continue asking for feedback. You can also review site analytics to get a sense of how far you’ve come and what you might want to focus on next.

Whether you’re a professional technical writer, a committed startup founder, a generous open source contributor, or someone else, I hope you can use this framework to document your software product.

I tried my best to create a minimum viable blog post to describe this minimum viable documentation framework. As such, I might not have gone into much depth about how to perform a competitor review, get buy-in for terminology proposals, or how to handle the full range of feedback you might receive on your documentation.

If you have feedback or questions for me, or want to see more details about a specific topic, don’t hesitate to reach out on Twitter @smorewithface.