Plain, literal English for instructions and docs

--- name: plain-literal-english-for-instructions-and-docs description: "Rules for writing procedures, runbooks, help articles and error messages that are short, literal and easy to translate. Use when writing or editing technical instructions, not marketing copy." --- Apply this whenever you write or edit text that tells someone how something works or what to do: procedures, setup guides, runbooks, help articles, release notes, error messages and reports. Do not apply it to marketing or brand copy. Decide the kind of text first - Steps (the reader acts): one action per numbered step, starting with a verb. Keep steps under about 20 words. - Explanations (the reader understands): short paragraphs on one topic each, sentences under about 25 words. - Keep steps and explanations apart. Put background before the steps, not inside them. Sentences - Use the active voice and the simple present or simple past. - Put the condition first, then the action: 'If the upload fails, check the file size.' - Say 'must' for requirements. Drop soft words such as 'should', 'might' or 'may want to'; decide whether the step is required or remove it. - No contractions, idioms or jokes; they do not translate. Words - Pick one term for each thing and keep it throughout. Do not alternate 'account', 'profile' and 'user page' for the same screen. - Prefer short common words: use, before, if, start, so that. - Cut filler: 'simply', 'easily', 'just', 'in order to', 'please note that'. - Break long noun strings into phrases with 'of' or 'for'. Warnings - State the instruction first, then the reason: 'Do not unplug the device during the update. The update can fail and lock the device.' Leave untouched - Code, commands, file names, field labels, exact error text and product names. Before you finish - Check your three longest sentences and split any that run over the limit. - Scan for soft modals, contractions and changing terms, and fix them.

Before: 'Once you've gone ahead and logged in, you should probably head over to the settings area, where you can easily tweak your profile and maybe update the notification preferences on your user page if needed.' After: Change your notification settings 1. Sign in. 2. Open Settings. 3. Select Notifications. 4. Choose the alerts you want to receive. 5. Select Save. If Save is not available, refresh the page and try again. Notes on the edit: - Split one 40-word sentence into five steps. - Removed 'probably', 'easily', 'maybe' and 'gone ahead'. - Used one term, 'Settings', instead of 'settings area' and 'user page'.