This is a draft cheat sheet. It is a work in progress and is not finished yet.
Solution Title
Should be written in the first person |
Should be action based |
EG: MS Outlook crashes on startup |
Solution Problem
Description of the problem in terms of the End User |
Different problem descriptions as separate bullet points |
EG: MS Outlook crashes with error: E12345 |
Solution Workaround & Resolution
Assume basic technical knowledge |
Write in complete sentences, including subject, verb and object |
Use simple language, omit non-essential words and avoid technical jargon |
Use present tense |
Address the reader in second person (EG: you, your) |
If the article is addressing a technician, address the technician in second person and the end user in the third person as a proper noun (EG: the End User / they, their) |
End each sentence with a period, unless it could cause confusion |
Solution Cause
Problem Record |
Reference a problem record. |
Suspected: |
Denotes a suspected cause |
Confirmed: |
Denotes a confirmed cause |
Different causes |
on separate bullet points |
|
|
Preferred Action Words
Check/Uncheck |
A checkbox |
Choose |
A menu option |
Double-click / Click / Right-click |
A button on-screen |
Download |
Hyperlinked file from the web. |
Select |
From a drop down menu |
Enter |
Text into a field |
Log in / Log out |
To a system or account |
Open / Close |
An application or file |
Press |
A key or physical button |
Instruct / Ask |
An end user |
Connect / Disconnect |
To a remote server or service |
Install / Uninstall |
An application or driver |
Browse to |
A network location |
Text Formatting
Actions |
In Italics |
Noun |
In Bold |
Font |
Arial |
Font Size |
16pt |
Alignment |
Left-Aligned |
Instructional Lists |
Numbered Bullet Points |
Informational Lists |
Standard Bullet Points |
Hyperlinks |
Descriptive, not just "Click Here" |
Line Breaks |
Before and after images & between paragraphs |
|
|
Screenshots
When to use |
If more than three settings need to be changed in a single window, or if an option / icon is difficult to locate |
File Type |
PNG / JPG / JPEG |
Image Alt-Text |
Appropriately detailed |
Maximum dimensions |
1000px height, 600px width |
Cropping |
Always keep window title |
Resizing |
Keep aspect ratio, do not warp image |
Image Border |
Only if having a border aids clarity |
|
