Explaining technical subjects.
WHERE IT HELPS
Explaining a concept at a specified level Producing first drafts of documentation Turning technical notes into readable prose Writing for a non-technical audience
WHAT TO BE CAREFUL WITH
Version-specific details, which go stale Commands and configuration, which must be tested Security guidance, where an error causes harm Specifications and figures
THE CENTRAL RISK
Confident technical instructions that are subtly wrong.
A command that looks right and does something else is worse than no instruction.
WHAT TO ALWAYS DO
Test every command and procedure before publishing Check version-specific claims Have someone technical review anything consequential
FOR A NON-TECHNICAL AUDIENCE
"Explain this for someone who has never used a command line. Define every term. Say what could go wrong."
WHAT IMPROVES TECHNICAL WRITING
Saying what the reader will see after each step Warning before anything irreversible Telling them how to undo it
THE INSTRUCTION WORTH ADDING
"Include a warning before any step that cannot be undone."
