Integrated Q&A in product documentation

GR Stocks

Product documents that describe customer problems and solution options help product teams align their understanding and their work. As a product manager, you might write these documents, or co-write them with other team members. Either way, you want documents to generate feedback, trigger discussion, and surface questions.

Questions play a central role in collaboration. And as every public speaker knows, questions create better discussion than comments.

Not a question, more of a comment, really

Document-based collaboration tools, such as Google Docs and Notion, use a paper-based metaphor for review comments. Document authors collaborate by editing the text and adding comments in the margin, a print publishing concept.

Someone adds a comment, then someone else reads it, and possibly updates the document. After that, the comment becomes obsolete, often hidden or deleted. But that doesn’t always happen: we don’t always want to delete the comments. Review comments sometimes highlight issues that we cannot resolve. They hang around to preserve the discussion, like footnotes that don’t belong in the main text.

Critical questions

Delibr and Slite go further than the usual document review comments functionality, in their documents. They both treat questions as a special kind of comment.

Delibr uses questions to track decisions. The product documentation explains that, ‘we believe a good specification can be simplified to a list of questions and decisions’. Delibr documents make questions in the text explicit, along with their decision status:



Slite documents also include explicit questions:

Slite extends Q&A collaboration further by providing a whole ‘page’ for a question’s discussion thread, where you can invite other participants, and set a due date for resolving the discussion. Slite also has a separate page for all questions and answers, where you can browse open questions and their due dates.

By making questions explicit, both Delibr and Slite embed collaboration in the main document text. They also highlight questions’ resolutions, either as decisions or answers.

Decisions

Delibr provides a user interface for marking a question as decided, and providing additional decision information to document the decision:

This provides more context than conventionally documented decisions, by marking which decisions the document encapsulates, and their rationale. When you use multiple-choice decisions, instead of yes/no decisions, you also capture the rejected alternatives. This provides a tidier alternative to preserving document comments.

Answers

Slite questions capture discussion differently, by preserving a whole discussion thread on a separate page, and letting you highlight one response as the answer:

This has less structure than Delibr’s multiple-choice questions, but preserves more discussion without cluttering the main document.

Resolutions

As collaboration tools evolve, we progress from translating historical paper based approaches to software tools. While inline comments still live in a metaphorical paper margin, inline decisions make documents more dynamic and more structured.

Delibr’s and Slite’s approaches seem equivalent: because you can phrase comments as questions, list options in follow-up comments, and phrase answers as decisions. More importantly, both explicitly identify questions and their resolutions, with the potential to avoid the friction of formal decision records.