Tips for writing SaaS documentation
If you’re writing documentation for a software-as-a-service (SaaS) product that releases constantly, it’s easy to be overwhelmed by the amount of new functionality being released that needs to be documented.
But do you really need to document all of it? Nope.
Instead, document the hidden, document the weird, and document the why.
Consider every new product feature in terms of what the user cares about. Don’t document what the product can do—document what the user wants to do.
I recommend adopting minimalism in your documentation, especially if you’re trying to keep up with the fast-paced release cycle of a SaaS product. Anni Bond wrote an excellent overview on Adopting minimalism in your docs.
I use a series of questions to keep my documentation minimal and to focus my documentation efforts.
Documenting a feature
When reviewing a feature, consider the following:
- What might confuse someone about this?
- What could go wrong that they’d need help fixing?
- What is different enough from existing product experiences that might require shaping a mental model?
- Where do these changes fit in a customer workflow?
- In what ways could the feature be improved to be clearer or easier to use (without documentation)?
It’s often helpful to use your role as a user advocate to push for product improvements rather than documenting around problems with the user experience.
Reviewing doc feedback
When reviewing documentation feedback from a customer or the field, consider the following:
- Was more than one person confused?
- Is this feedback related to one specific edge case?
- Is this an actual error? How much time will it take to track down?
- What led to someone being confused? Is their personal mental model different?
- Is it actually confusion about how the product works and isn’t necessarily a documentation task?
Try to understand the root of the feedback. Rather than giving in and adding a quick note about anything and everything, consider what improvements might make sense to make to the documentation or the product to address the core issue.
Documenting strange behavior
When reviewing a request from PM or engineering to document something weird, consider the following:
- Is this time-limited?
- Is this behavior only going to be true until a certain point of time?
- Is this feature-limited?
- Is this behavior only going to be true until a feature gets refactored/improved/enhanced?
- Is that work scoped and planned for anytime soon?
- Is this actually a bug that should be in the release notes and nowhere else?
- How many people are affected by the weird thing?
- How common or likely is the weird thing to occur in actual customer environments?
Write less for success
It might seem like I’m telling you to find a lot of reasons to avoid writing documentation. I am. It’s important to focus on the documentation that customers are going to go looking for, instead of making sure the entire product functionality is documented.
Say your product requires people to confirm their email address before they can start using it.
Will customers read documentation about how to confirm their email address? No.
Do you need to write documentation about how to confirm an email address? Also no.
If you have a strong understanding of your users and their mental models, you can make this same determination for other, more complex, workflows in your product.
Stop trying to keep up with the product and start helping the people using it.