2 ms·
I really miss old-school printed documentation's "Theory of Operation" section. To me it's the most useful way to bridge this gap. The technical and operation
by akira2501 3y ago
I really miss old-school printed documentation's "Theory of Operation" section. To me it's the most useful way to bridge this gap. The technical and operations manual describe all the parts and how they function, but the theory of operation really laid out how and _why_ all of these things were structured the way they were.
It also forced the designers to think in those terms and to document the product from an overall perspective rather than a component perspective. It was high level enough to be useful, but not so high level as to be abstracted into hand holding tutorial exercises.
I feel like most modern software documentation entirely misses this component and would benefit greatly from having it.
- giovannibonetti 3y agoRelated: Diátaxis - A systematic framework for technical documentation authoring [1] "The Diátaxis framework aims to solve the problem of structure in technical documentation. It adopts a systematic approach to understanding the needs of documentation users in their cycle of interaction with a product. Diátaxis identifies four modes of documentation - tutorials, how-to guides, technical reference and explanation. It derives its structure from the relationship between them.(...)" [1] https://diataxis.fr/ https://diataxis.fr/
- kaycebasques 3y agoCan you link me to a good old school "theory of operation" section? I get the idea but I want to see firsthand what you mean.
- akira2501 3y agoThe older Harris Corporation AM and FM transmitter manuals was what came to mind when I wrote that. As equipment got modernized, there was less for the operator to know, so they get shorter and shorter over time. Look at the SX-1 AM manual under "Principles of Operation" to something like the HT-35 FM manual under the same. Also.. early computer manufacturers like MITS had manuals in a similar vein for their Altair 8800 box but you can find many examples in this space, there's a stub of a Wikipedia page just for it: https://en.wikipedia.org/wiki/Theory_of_operation https://en.wikipedia.org/wiki/Theory_of_operation