Why Stack Overflow's Documentation effort failed -- a few thoughts from a technical writer's perspective

Stack Overflow, mostly known as a forum for answering niche software questions, recently tried to launch a Documentation component to their site. The goal of Documentation was to 'do for Documentation what we did for Q&A'. In other words, provide substantial, valuable information that could be the go-to source for tech docs instead of just one-off answers around niche topics. However, the effort failed and now Stack Overflow is sunsetting their Documentation. Read more »

Tech docs and Agile: Alternatives to integrating into engineering Scrums (Part 2)

This is part two in a series on Agile and tech docs. In the previous post, I outlined challenges in integrating into engineering Scrum teams. Some alternatives to Scrum include Kanban, Extreme programming, Waterfall, and various productivity methodologies. The most compelling solution, to me, seems to be to form your own documentation-focused Scrum. This allows you to keep with the same project management approach and language in the company, while also allowing you to avoid the pitfalls previously described with integrating into an engineering Scrum. Even so, there's not an extremely compelling reason for docs to adopt Scrum, so its main aid might be to give you a disciplined approach to your doc work. Read more »

Tech docs and Agile: Problems with integrating tech writers into engineering Scrums (Part 1)

Although it seems like documentation should be treated like other features worked on by a Scrum team, frequently it is not. When tech writers try to integrate into engineering Scrum teams, they usually run into a host of challenges. These challenges stem mainly from floating across multiple projects. Often doc tasks aren't assigned points or grouped in with other tasks in a real sprint, nor are tech writers co-located with project teams. This is a two-part post. In this first part, I outline problems for tech writers integrating into Scrum teams. In part 2, I explore solutions. Read more »

Why simple language isn't so simple: the struggle to create plain language in documentation

Although you can adjust your content's style to be simpler and more readable, technical documentation introduces many new terms and concepts for readers to learn. Many readers who don't already understand the discourse community may find this language impenetrable. Glossaries and inline tooltips can potentially help novice users, but there's no easy solution for simplifying your language for both novice and expert users. Read more »