The whole category in one page.
THE ONLY MEASURE OF SUCCESS IS WHETHER THE READER COMPLETES THEIR TASK
Documentation that is accurate, complete and unusable has failed. Readers arrive with a problem, in a hurry, and they scan rather than read.
EXPERTISE MAKES IT IMPOSSIBLE TO SEE WHAT IS NOT OBVIOUS, WHICH IS WHY YOU MUST HAVE SOMEONE WITHOUT THE KNOWLEDGE TRY TO USE IT
Watch without helping, because every intervention conceals a defect, and note where they hesitate as well as where they fail.
ORGANISE BY THE TASK THE READER IS PERFORMING, NOT BY FEATURE — THEY KNOW WHAT THEY WANT TO ACHIEVE, NOT WHICH FEATURE ACHIEVES IT
ONE ACTION PER STEP, VERB FIRST, AND EVERY WARNING BEFORE THE STEP IT CONCERNS RATHER THAN AFTER IT
USE THE SAME WORD FOR THE SAME THING EVERY TIME, BECAUSE VARIETY IS A VIRTUE IN PROSE AND A DEFECT IN TECHNICAL WRITING
QUOTE ERROR MESSAGES VERBATIM AND ORGANISE TROUBLESHOOTING BY SYMPTOM, SINCE READERS SEARCH FOR EXACTLY WHAT THEY ARE SEEING
WRONG DOCUMENTATION IS WORSE THAN NONE BECAUSE IT IS FOLLOWED — UPDATE IT AS PART OF THE CHANGE, SINCE UPDATING AFTERWARDS DOES NOT HAPPEN
TEST EVERY EXAMPLE AND RETEST AFTER CHANGES, BECAUSE BROKEN EXAMPLES DESTROY CONFIDENCE INSTANTLY
REVIEW WHAT PEOPLE SEARCH FOR AND DO NOT FIND, WHICH IS THE CLEAREST INDICATION OF WHAT TO WRITE NEXT
AND AIM FOR A MINIMUM STANDARD RATHER THAN A COMPREHENSIVE IDEAL, BECAUSE COMPREHENSIVE DOCUMENTATION IS RARELY ACHIEVED AND THE ATTEMPT PRODUCES NOTHING
