There’s an argument to be made for documenting Worst Practices, too. Along with “Unsupported configurations”, “Practical limitations”, “Unmet use cases”, and “Failure modes”.
That kind of information is absolute gold for solution design. Far too often I've found myself trying to discern the true envelope of some subsystem's capabilities by the negative space implied in the product docs, a task sometimes comparable to reading tea leaves.
Alas, many product managers regard documentation as propaganda, thus in the interests of fragile egos such topics are commonly omitted.
I call the parts of my documents that address limitations and unmet use cases the "Not Gonna Do It" sections. In my case, it's especially important to document functionality that was considered and rejected, and why.
Where performance, security, and similar qualities were recommended by programmers but rejected by management, I especially want to record those for later reference in case of problems. Maybe what I write doesn't make it into end-user facing product documentation, but it's on the record. To give an example, at one project I consulted on, all of the user interface text was written in english, with US measurements with no i18n or l10n system. The company I was working with has customers from, if not worldwide, at least all of the western hemisphere. About six months later project management finally came to the realization that they were going to need at the very least multiple languages, and a lot of work was ahead to retrofit.
That kind of information is absolute gold for solution design. Far too often I've found myself trying to discern the true envelope of some subsystem's capabilities by the negative space implied in the product docs, a task sometimes comparable to reading tea leaves.
Alas, many product managers regard documentation as propaganda, thus in the interests of fragile egos such topics are commonly omitted.