![[personal profile]](https://www.dreamwidth.org/img/silk/identity/user.png){kind=small}
Paraphrasing an exchange that took place via bugzilla:
Developer: We need to say in the release notes that the product works like [foo].
Me: (Looks at documentation) We already say in the documentation that the product works like [foo]. Do we really need a release note?
Developer: Yes. We need to change the documentation to say that the product works like [bar], and then we need to write a release note to say that the product works like [foo].
Me: Wait, I'm confused. Does the product work like [foo] or [bar]?
Developer: It works like [foo]. But this is a regression. It should work like [bar]. Therefore the documentation should say it works like [bar], and then the user should go to the release notes to find out that it actually works like [foo].
Me: (Tries to comprehend a view of the universe in which this is a better experience for anyone) Sorry, department policy is to document the product the way it actually works, not how it should work.
Developer: We need to say in the release notes that the product works like [foo].
Me: (Looks at documentation) We already say in the documentation that the product works like [foo]. Do we really need a release note?
Developer: Yes. We need to change the documentation to say that the product works like [bar], and then we need to write a release note to say that the product works like [foo].
Me: Wait, I'm confused. Does the product work like [foo] or [bar]?
Developer: It works like [foo]. But this is a regression. It should work like [bar]. Therefore the documentation should say it works like [bar], and then the user should go to the release notes to find out that it actually works like [foo].
Me: (Tries to comprehend a view of the universe in which this is a better experience for anyone) Sorry, department policy is to document the product the way it actually works, not how it should work.
