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 the 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 do a favor for future readers if you clean it up. It’s like paying out the debt with a small comprehension refactoring, but the documentation and not the code.

Resolving discussion 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.