Comment by ChrisMarshallNY
2 years ago
Having just completed my first (and last, for a while) shipping SwiftUI app, I very much think that documentation has been treated in shabby fashion, in the modern tech scene. I sorely miss the work done by all those great tech writers that Apple fired. Their engineers are terrible documenters.
I'm always a bit leery of "dogmatic" approaches, though, because they tend to develop a "priesthood," that refuses to bend; even when reality demands it.
In my experience, the initial developers of the dogma use it to marvelous effect, but subsequent "priests" screw the pooch; sometimes, turning the approach into a curse. Many good ideas have been destroyed by too-rigid applications (What is "Agile"?).
I see any documentation as having basically two faces: The maintainer, and the user. Each, has drastically different needs, and should probably be addressed by completely different teams.
As has been alluded to, in other comments, you can have issues with multiple instances of documentation, falling out of sync (the curse of most wiki-style documentation), but results matter. If the multiple instances can be effectively synced, then the documentation is effective and useful to its consumers. If no one reads the perfectly formatted and synced documentation, it's worthless.
On SNL, Phil Hartman[n] used to play The Anal-Retentive Chef. In one skit, he spent so much time prepping, that he couldn't actually demonstrate the recipe.
I see a lot of that, in tech. Toolchains and libraries that are absolutely perfect, but are unusable, in practice.
Documentation is an amalgam of many disciplines; human nature/psychology, graphic design, information architecture, technical infrastructure, publishing and distribution, etc.
I really think it's often treated as an afterthought, in most projects, and I believe that it should be a first-class consideration, at the Requirements stage, onwards.
I don't think of diataxis as a dogmatic approach, but rather a pragmatic one. You can dive pretty deep into the weeds in how to structure your documentation, but this is a very good training wheels until you find places that leak.
I agree, but I guarantee that it will become dogma.
I strongly suspect that few of the originators of dogma considered their work as such.
As I have gotten older, I have learned that "It Depends" is the only true dogma for almost all aspects of my life.
> Many good ideas have been destroyed by too-rigid applications
This is an interesting perspective that I disagree with. You seem to be saying that a general misunderstanding or misapplication of a good idea degrades the idea to a point that "destroys" it.
On the contrary, I believe there is experience to be gained in practice: either the initial idea wasn't good after all, in which case we're destroying an illusion; or the poor examples serve to refine the idea by clarifying some ambiguity that, interpreted wrongly, leads to failure.
Perhaps your argument is that many people may become familiar with the bad implementations and the idea's popularity will decline, depressing demand for refined implementations. This is likely true, but reflects the tragedy of the anticommons, not a degradation in the idea itself.
Well, what I mean, is that folks invest in the dogma, to the point where they refuse to accept any changes to fit realities, and often believe that they can apply the dogma, in areas, or in a manner, where it is not appropriate.
There's an old Swiss Army saying "When the map and the terrain disagree, believe the terrain.".
People who invest in dogma, refuse to look at the terrain. The map is The Only Source of Truth.
I believe that most dogma comes from something that works in one or more contexts, and may actually be highly effective, in other contexts, as long as it is adjusted for context. That last part, is what kills it. People refuse to change, and the dogma gets a bad name as a "failure."
You see this constantly.