Revise documentation, many times, and on separate days to catch confusing parts.
Beware of ambiguities, e.g. X may not do Y. Refer to definitions, e.g.
RFC 2119
.
Put yourself into different roles, e.g. the person just looking for samples,
the person who wants to read up on every nook and crany, the person who has no
technical background etc.
In writing class, I was taught to target a specific reader. The above suggests
that I target multiple types of readers with the same piece. I’m hesitant to
overrule what I learnt. Or is it more that the same reader will have different
objectives in each read? Sometimes I read docs in order to understand the design;
other times, I’m in search of a quick example to get the syntax.
In writing class, I was taught to target a specific reader. The above suggests that I target multiple types of readers with the same piece. I’m hesitant to overrule what I learnt. Or is it more that the same reader will have different objectives in each read? Sometimes I read docs in order to understand the design; other times, I’m in search of a quick example to get the syntax.
...