You write a specification draft and share it with colleagues for feedback.

With Google Docs, Notion, or Confluence, typically, colleagues leave contextual feedback on specific lines of the document. From there, an entire discussion can evolve.

A specification with many unresolved comments is a time sink for everyone who touches it. Not only do they need to read the spec, they also need to follow all the threads and discussions and find the final opinion. It’s not uncommon for some of them to hang without a resolution, leaving it to whoever made the implementation.

As a specification owner, you are responsible for resolving these discussions and updating the document with the resolution.

If you’re not the specification owner but come across a specification with unresolved comments, you’ll help future readers by cleaning it up. It’s like paying off the debt with a small comprehension refactoring, but for documentation instead of code.

Resolving discussions is essential for the same reason we write the specification in the first place — to ensure everyone is on the same page and to keep the context in history. Please don’t forget about it.