8 ms·
Perhaps add "Docs must be more than screenshots or follow-the-monkey instructions". If it's not appropriate to explain what the system is doing, it is then appr
by drpixie 3y ago
Perhaps add "Docs must be more than screenshots or follow-the-monkey instructions". If it's not appropriate to explain what the system is doing, it is then appropriate to link to something that does explain it.
Docs that say/show anything like "Select Enable VTd to enable the VTd function" are useless docs. I won't bother providing a list of docs that do exactly that, but start by looking at your BIOS help!! I think we can assume that I understand "click" and "enable", but we should also assume that only the project engineers understand the acronyms and special functions. How about "The VTd function (Intel's Virtual Technology - Direct IO) permits virtual machines to do IO with fewer buffer transfers. Virtual machines may run faster, but could corrupt disk."
- ramijames 3y agoI mean, sometimes that is exactly what is appropriate. For some use cases you just want clear step by step instructions. Sometimes you will want in depth technical explanations. That's really the point I made in that piece: you have to know who your audience is, and write accordingly.
- mooreds 3y agoI have found this framework helpful in thinking about the four kinds of docs: https://diataxis.fr/ https://diataxis.fr/ * tutorials * how-to guides * reference * explanation