Documentation as an application: enabling interactive content that is tailored to the user¶
Description
The modern web platform provides a rich canvas for presenting content, making it possible for documentation to offer a user experience that more closely resembles an application rather than a traditional user manual. Exploiting these capabilities and making them easily accessible to technical writers requires corresponding advancements in content authoring systems.
As a technical writer and engineer in the Docs Product team at Stripe, I'm responsible for developing the new authoring system for our next-generation documentation platform. In this presentation, I'll cover:
- How investing in richer documentation that provides a more engaging and intuitive experience can increase the success of our users and help them get to market faster with our products
- How we're dynamically tailoring content for individual readers and selectively surfacing relevant information to users with specialized requirements, based on factors like geographic location and attributes of the user's logged-in account
- How we've evolved our authoring system towards a fully declarative format that supports user-specific customization, client-side interactivity, and deep static analysis while keeping code decoupled from content
- How our cross-functional Docs Product team treats our documentation as an application, driving concurrent improvements to both the user-facing documentation experience and internal authoring tools
Features like dynamic content generation, contextual awareness, and client-side interactivity are making documentation more like software. But taking advantage of these features leads to more code creeping into content, resulting in a steeper learning curve that can potentially discourage participation from prospective documentation contributors. In this presentation, I'll share the lessons learned while building an extensible Markdown-based content format that supports application-like user experiences and provides the technical advantages of documentation-as-code while avoiding the complexity and elevated barrier to entry, ensuring that content authoring remains inclusive and accessible.
- Conference: Write the Docs Portland
- Year: 2020
