Command Palette
Search for a command to run...
Comments
Join the discussionNo comments yet. Be the first to comment.
Search for a command to run...
No comments yet. Be the first to comment.
What if the goal of writing documentation was not to accurately describe a system? How it works, how to use it, etc.
What if, instead, the goal was to describe how the system should work?
Surely, it can’t be right to treat documentation like a fantasy novel. It does need to be factual.
And yet, if we write how the system should work, then analyze the gap between reality and this fantasy, we can go and plug that gap.
Or put another way, if one writes factual documentation, and struggles to make it easy to understand, it may be that the issue lies not in the doc, but in the thing being documented.
A similar idea is that your FAQ is your bug list. Why does this question need to be asked in the first place? Can’t the system be sufficiently intuitive to side step the question completely?
In the end, it may be possible to document how the system should work and how it does work, though it may require some iteration(s) of tweaking the system itself to get there.
