At Spice Sage, we believe that great products aren’t just built—they’re communicated. As we’ve developed our spice subscription platform, one lesson has become increasingly clear: bringing documentation teams into the product development process early doesn’t just create better guides—it creates better products.
The Traditional Documentation Dilemma
We’ve all been there. The product is built, features are locked, the launch date is looming, and someone suddenly asks: “What about the user documentation?”
This last-minute scramble typically leads to:
- Documentation writers racing to understand complex features
- Engineers distracted with explanations when they should be fixing bugs
- User guides that feel disconnected from how people actually use the product
- Documentation that describes the product rather than solving user problems
When our team started developing the Spice Sage mobile app, we initially followed this traditional approach. The result? Our beta testers were confused by our “intuitive” NFC spice scanning feature, and we had to delay our testing phase to create better guidance.
Shifting Left: Documentation as a Product Requirement
For our web platform development, we tried something different. We included our documentation specialist from day one of the requirements gathering process. The results were transformative.
How We Did It
Documentation Prototyping: Created documentation prototypes before building features
Documentation User Stories: Along with functional requirements, we created documentation user stories
As a new user, I want clear instructions on setting up my flavor preferences so that my first spice box matches my tastes.
Documentation Acceptance Criteria: Each feature included acceptance criteria specifically for documentation
✓ Includes step-by-step visual guide
✓ Provides examples of preference combinations
✓ Explains how preferences influence recommendations
Documentation Debt: We tracked “documentation debt” alongside technical debt
The Benefits We’ve Seen
1. Better Product Design
When our documentation team struggled to explain how users should create custom spice blends, we realized the interface was too complex. This led to a simplified design that required less explanation. The best documentation is often no documentation at all!
2. Reduced Development Rework
By thinking through how to explain features before building them, we identified gaps in user flows. For our spice freshness tracking feature, documentation planning revealed we hadn’t considered how users would handle transfer between containers.
3. More Accurate Time Estimates
Including documentation in sprint planning gave us more realistic timelines. What seemed like a quick feature to develop sometimes required extensive explanation—a sign of underlying complexity.
4. Improved User Testing
Having draft documentation available during user testing provided a safety net while revealing which concepts needed more explanation. Our spice origin AR feature made perfect sense to the development team but confused users until we added context in the documentation.
5. Documentation That Actually Helps
Most importantly, our documentation became genuinely helpful rather than merely descriptive. Instead of explaining what each button does, our guides now focus on helping users accomplish real goals.
How to Integrate Documentation Into Your Requirements
Ready to bring documentation earlier into your product development process? Here’s our approach:
1. Invite Documentation to the Table
Include documentation specialists in:
- Product discovery sessions
- User research reviews
- Requirements workshops
- Early design reviews
- Sprint planning
2. Create Documentation Requirements
For each major feature, identify:
- Key user education needs
- Complex workflows requiring guidance
- New concepts needing explanation
- Documentation success metrics
3. Prototype Documentation First
For complex features, try writing the documentation before finalizing the design. If it’s hard to explain, it might be hard to use.
4. Test Documentation Early
Incorporate documentation into usability testing by:
- Observing where users look for help
- Testing draft guides alongside prototypes
- Measuring task completion with and without documentation
5. Define Documentation Done Criteria
Make documentation part of your definition of done:
- Support team trained on new features
- User guide updates completed
- Help content integrated into the UI
- Knowledge base articles published
Real Impact on Our Bottom Line
This approach hasn’t just made our users happier—it’s had measurable business impact:
- 42% reduction in spice freshness tracking support tickets
- 28% increase in recipe feature engagement
- 15% faster onboarding time for new subscribers
- 98% of users successfully complete NFC tag setup on first try
Getting Started at Your Company
You don’t need to transform everything overnight. Start with these simple steps:
- Invite documentation team members to your next planning session
- Include one documentation user story in your next sprint
- Try writing a help article for a feature before implementing it
- Review existing documentation to identify product improvement opportunities
At Spice Sage, we’ve learned that documentation isn’t something you create after the product is built—it’s an integral part of building the right product in the first place.
Remember: If a feature is difficult to document, it might be difficult to use. By bringing documentation into requirements, you’re not just planning for better guides—you’re planning for better products.
What’s your experience with documentation in the product development process? Have you found creative ways to integrate user education earlier? Share in the comments below!