Mixing code and content provided a natural way to programmatically tailor the docs to the developer, but it posed serious challenges to quality and maintainability when the body of content grew to hundreds of pages. The content freely mixed HTML, Markdown, Ruby, and ERB helper functions. The legacy documentation platform that we replaced was a monolithic Ruby application built with ERB templates and Sinatra routing. To understand how we got here it's important to understand where we started. Over several years, we learned how to balance interactivity, customization, and authoring productivity while undertaking a major overhaul of our documentation platform. Delivering a good user experience without compromising the authoring experience required us to develop an authoring format that enables writers to express interactivity and simple page logic without mixing code and content. These features result in a high-quality user experience that reduces friction and contributes to the success of developers.įor these capabilities to have the desired impact we have to make it easy for writers to use them in their content. We tailor the content to the individual user, conditionally displaying content based on their location or the Stripe features they use. We have client-side interactivity, like checklists and collapsible sections.

For example, we incorporate a user's own API test key into code samples, making it possible to copy and paste code that seamlessly works with the user's own account. Then tweak the markup every so often, when things change.At Stripe, our product docs are designed to feel like an application rather than a traditional user manual. Use tools like and that create diagrams from markup and check the markup into a SystemArchitecture folder in your GIT repository. Complexity is killing software developersĭont Document! Instead Diagram the system.Yes, not a flowchart, but I like the concept implemented at. We need a flowchart editor that doesn't give you carpal tunnelĪ couple of relevant links: - If you draw a lot of sequence diagrams, this one is a feature-rich type-to-diagram life saver: - For component/architecture diagrams.Time for a shout-out for (in my opinion) the coolest and most useful free tool on the web: Use this all the time for my work and the ability to share a diagram with a url is a killer use case. Have you seen ? No JAR needed, just a web browser. D2: A new declarative language to turn text into diagrams.

Web sequence diagram online