Sociological considerations in designing an internal documentation platform¶
Description
Internal documentation – in this talk, canonical reference material written by software engineers for their colleagues – is crucial for the smooth functioning of a company, as can be attested to by anyone who’s been woken at 3 AM by an automated detector that nobody seems to have explained anywhere. But it’s also subject to very different tradeoffs than end-user-facing documentation is; prototypically, you’d imagine a lot more docs, subject to fewer review cycles, written by teams with very different norms, for which a content strategy is way harder to direct from on high.
The upsides of those trade-offs are very real: internal docs can make some simplifying assumptions about their audience, are lower-friction to edit, and are less constrained by a need to fit into a company-wide content strategy. Magnified by scale, however, the downsides of these trade-offs – like how much easier it becomes to let docs go stale or become fragmented – can grow into systemic sociological issues with internal docs culture.
So, what can we as documentarians do to ensure that our internal docs overcome those issues and remain effective? I’ll be talking about my experience at Stripe’s team tasked with answering that question. Most of my talk will focus on what sociological issues we’ve found in our internal documentation posture (many of which we think are generalizable!) – ones around freshness, fragmentation, discoverability, and more – as well as what opinionated unique features we’ve designed into our in-house internal docs platform to combat those issues. We think our approach has helped (developer satisfaction with Stripe-internal documentation has gone way up!) and want to share how we’ve recognized and remediated these kinds of problems.
- Conference: Write the Docs Portland
- Year: 2024
