4 ms·

Can we call it "Good Practices" instead, and make sure they qualify when they apply? Practices are rarely the best in all cases, and often change over time.

inopinatus 3y ago
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.
- cratermoon 3y ago
  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.
cratermoon 3y ago
I believe Rust uses the term "Blessed", as in https://blessed.rs/crates https://blessed.rs/crates, for things that are broadly trustworthy. I'm a bit old school, I fall back to "patterns" as "solutions to problems in context".
Ygg2 3y ago
Best is contextual as well. Best at what?

inopinatus 3y ago

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.

cratermoon 3y ago
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.

cratermoon 3y ago

I believe Rust uses the term "Blessed", as in https://blessed.rs/crates https://blessed.rs/crates, for things that are broadly trustworthy. I'm a bit old school, I fall back to "patterns" as "solutions to problems in context".

Ygg2 3y ago

Best is contextual as well. Best at what?