Building Community Guides People Use

A guide is valuable when it helps someone complete a task or make a decision with less uncertainty. Its usefulness depends on clarity more than length.

Start with the reader’s goal. Explain what the guide will help someone do and what it does not cover.

Put the essential steps first. Readers should not have to study the entire background before they can begin.

Use examples where decisions may be confusing. A short example can show how a general principle works in a real situation.

Name common problems. Tell readers what to check when a step does not work and where to ask for help.

Review the guide with a beginner. Someone unfamiliar with the process can identify assumptions that experienced contributors no longer notice.

Update the guide when the surrounding community changes. A useful document is maintained, discoverable, and connected to the people who rely on it.