3 ms·

The author previously discussed the four-document model and some additional kinds of documents at <https://buttondown.email/hillelwayne/archive/beyond-the-four-

The author previously discussed the four-document model and some additional kinds of documents at <https://buttondown.email/hillelwayne/archive/beyond-the-four-document-model/ https://buttondown.email/hillelwayne/archive/beyond-the-four...>, and goes into further detail about conceptual overviews and examples. Of the other kinds of documents he mentions, "Best Practices" are often the ones I look for early on when learning a new language or library. It's easier for me to get up to speed by emulating what works.

alexchamberlain 3y ago
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?
kaycebasques 3y ago
I think Procida's thinking about examples also works pretty well for best practices and anti-patterns: > You can and probably should use examples everywhere. I think that a well-crafted example can often illuminate something much better than a painstaking attempt to describe it fully and completely... Examples illustrate extremely effectively, whether they are illustrating how-to guides, explanation, or whatever. But examples on their own seem a bit deracinated. What are they examples of? Don’t they need context? Best practices and anti-patterns usually work best in the context of how-to guides or references IMO
- cratermoon 3y ago
  > Best practices and anti-patterns usually work best in the context of how-to guides or references I think it’s safe to say that all four-plus kinds of documents work best as a coherent whole, each revealing an aspect of the system in relation to the others

alexchamberlain 3y ago

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?

kaycebasques 3y ago

I think Procida's thinking about examples also works pretty well for best practices and anti-patterns: > You can and probably should use examples everywhere. I think that a well-crafted example can often illuminate something much better than a painstaking attempt to describe it fully and completely... Examples illustrate extremely effectively, whether they are illustrating how-to guides, explanation, or whatever. But examples on their own seem a bit deracinated. What are they examples of? Don’t they need context? Best practices and anti-patterns usually work best in the context of how-to guides or references IMO

cratermoon 3y ago
> Best practices and anti-patterns usually work best in the context of how-to guides or references I think it’s safe to say that all four-plus kinds of documents work best as a coherent whole, each revealing an aspect of the system in relation to the others