April 2024 Summaries

The Write the Docs conference in Portland emphasizes the importance of using research and metrics to enhance the value of software documentation, as demonstrated by various speakers who shared insights from their experiences. Key themes included the use of user testing and visual enhancements in documentation, as discussed in Dennis Dawson's presentation, and the challenges of maintaining SEO during platform transitions, as highlighted by Steven Hicks. Taylor Krusen explored the role of interactivity in documentation, while Michelle Irvine discussed the impact of high-quality documentation on developer performance, referencing findings from the DORA research program. Alistair Gray shared efforts to improve internal documentation at Stripe, and Tom Edmonds highlighted the need for quantifying technical writing efforts to demonstrate business value. The conference fostered an engaging environment with pre-conference activities and offered attendees valuable knowledge and networking opportunities.

API governance extends beyond creating and implementing standards with tools, emphasizing the critical role of people in the process. At Redocly, API councils, composed of cross-disciplinary experts, play a pivotal role in advising, reviewing, and overseeing API development, particularly thriving in a design-first approach where early input is crucial. These councils use the OpenAPI description as the definitive source for proposed changes, allowing for precise discussions and minimizing uncertainty. The council's diverse composition ensures that design decisions are well-rounded, integrating perspectives from developers, product specialists, and technical writers, who act as "customer zero" to foresee user challenges. The council process may follow a regular meeting structure or an asynchronous review style, both fostering comprehensive feedback and clear documentation while avoiding becoming a bottleneck. Long-term, dynamic involvement in the council is vital for sharing knowledge and maintaining a robust API ecosystem.