Start with the questions contributors already ask
A CMS may offer fields for a page title, summary, image, image description and related links, but the purpose of each field is not always obvious. A contributor might wonder whether a summary appears on the page, whether a title is used in navigation, or what belongs in an image description. When the answers live only in someone’s memory, editors spend time correcting the same mistakes.
Collect a few recent drafts and note where contributors hesitated or entered information in the wrong place. Ask editors which explanations they repeat most often. Use those observations to choose where instructions are needed. Not every field requires help text: a familiar field with a clear label may be easier to use without another sentence beneath it.
Explain the job of each field
Good field guidance answers three questions: what should go here, where will it appear, and what should the contributor avoid? For a summary field, you might write: “Write one or two sentences introducing this page. This text appears in article listings; do not repeat the title.” That tells the writer more than “Enter summary.” If the summary does not appear on every listing, describe its likely use without promising a placement the site cannot guarantee.
Make the label and instruction work together. “Button text” paired with “Use a short action, such as ‘View opening hours,’ rather than ‘Click here’” is easier to act on than a vague label such as “CTA.” For a link field, say whether it accepts an internal page selection, a full web address, or either. Clear instructions reduce guesswork before a reviewer ever sees the draft.
Put rules where they matter
Keep instructions close to the decision they support. If an image field needs alternative text, place that guidance beside the alternative-text field rather than in a distant handbook. Explain the task in everyday language: “Describe information in the image that a reader needs to understand this page.” If decorative images can be marked as decorative in your CMS, explain when to use that option. Avoid asking contributors to write the same description for every image.
Use validation for rules the system can check reliably, such as whether a required field is empty. Use help text for judgments the system cannot make well, such as whether a heading is useful. Be cautious with character limits: a strict limit can prevent publication even when slightly different wording would work. If a limit is necessary, tell contributors what it protects and check that the editing screen shows it clearly.
Keep the editing screen readable
Instructions lose their value when every field contains a long paragraph. Lead with the action a contributor needs to take, then add a brief example only where it resolves a common ambiguity. Use consistent terms across similar content types. If one editor calls a field “intro,” another calls it “teaser,” and the public page calls it “summary,” contributors have to learn three names for one job.
For complex tasks, use a short instruction in the CMS and keep the fuller explanation in an editorial guide. The field might say, “Choose one primary category. See the category guide if you are unsure.” This approach lets contributors finish routine work without leaving the editor while still giving them a place to resolve unusual cases. Make sure the guide and the field instruction do not contradict each other.
Test instructions with a real publishing task
Give someone who did not write the guidance a typical draft to enter. Watch for pauses, questions and places where they fill a field correctly for the wrong reason. Ask them what they expect to appear on the published page, then compare that expectation with the preview. A short test can reveal unclear labels, hidden required fields or instructions that assume knowledge the contributor does not have.
After revising the guidance, assign an owner to keep it current when templates or publishing practices change. Review field instructions when a content type changes, not just when someone reports a problem. The goal is not a perfect explanation of the CMS. It is a set of timely prompts that helps contributors make sound choices and gives reviewers fewer preventable issues to fix.
