DesignWIKI

Fil Salustri's Design Site

Site Tools


wiki:start_with_a_bang

Start with a Bang

Make sure every page starts with a tight, clear, and direct statement of what the reader will gain by reading it.

Consider the following draft version of a piece of documentation about editing wiki pages.

When editing a topic, a nearly perfect preview is provided under the text editing box, but the preview is not dynamic. As you edit content in the editing box, the preview does not automatically refresh.

To update the preview without stopping the edit session, click on the PREVIEW button.

Things wrong with this:

  • “When editing a topic” is pointless – the whole topic is about editing.
  • The last sentence is the most important. Start with it.
  • The first paragraph is too complex.

A better version would be:

To update the preview without stopping the edit session, click on the PREVIEW button.

  • A nearly perfect preview is given under the main editing box.
  • But the preview is not dynamic: as you edit content, the preview does not refresh automatically.

This version is better, and simpler to read:

  • It starts with a highlighted phrase that describes the sort of thing the reader would be looking for.
  • It's instructional - it tells you straight out what to do.
  • A description of what happens and typical results follows the instruction, which corresponds to the order of events the reader will experience following along.
  • The caveats and special conditions are at the end so as not to distract the reader from understanding the main points.
wiki/start_with_a_bang.txt · Last modified: 2020.03.12 13:30 (external edit)