How to document WordPress custom fields for content editors
An editor opens a WordPress page and finds a field called subtitle_2. A second subtitle? An old experiment? Something that quietly changes the layout? The only person who knew left the project months ago.
Now every edit comes with a small mystery attached.
Custom fields are great when they make content easier to structure and maintain. They become a problem when editors don’t know what belongs in them or what happens after they press save. Good documentation explains each field from the editor’s point of view, not just the database key.
Begin with the page the editor is making
List the content type and the template that uses the fields. A field can mean different things on a product, an article or a landing page. Start with the job the editor is trying to complete and identify where each field appears on the published page.
For every field, write down its label, purpose, expected content, whether it’s required, any length or format guidance, and what the page does when it’s blank. Include an example only if it’s generic and accurate. Don’t invent a fake client or product just to make the guide feel concrete.
Explain whether a field affects the visible page, metadata, a button, a related-content module or another system. An editor should be able to predict the result of a change before publishing it. If the field has no visible or operational effect anymore, verify whether it is still needed before documenting it as current.
Use labels people recognise
A database name is handy for developers and confusing for editors. Prefer a clear label like “Short introduction” over intro_copy_v2. Add help text that says what to enter and where it appears. “Enter subtitle here” under a field called “Subtitle” just repeats the name. When I train clients to run their own sites, unclear labels cause more support questions than almost anything else.
Use consistent language across similar templates. If “summary” means the short text shown above an article on one template and a search snippet on another, choose clearer labels or explain the difference. Avoid using the same label for fields with different purposes.
If a field is part of a group, explain the group as well. A repeater or flexible content block may have several options, each with different output. Show the order in which editors should add items and what happens if an item is empty. A screenshot can help, but keep the written description accessible and current when the interface changes.
Document rules and edge cases
State when a field is optional and what “leave blank” means. The page may hide the section, show a fallback, or display an empty space. Editors need to know which behaviour is intended. If a field is required for a legal or commercial reason, explain who can approve an exception.
Describe formats where they matter: date format, link destination, image dimensions, file type, maximum length. Don’t document limits based on what happened to fit in one test. Check the rule in the actual CMS or template first.
Cover common edge cases such as a long heading, an external URL, missing imagery or multiple items. A field that works for the usual case may produce a broken layout in an unusual one. If the template does not handle a condition, record the limitation and tell the editor what to do.
Test the documentation with an editor
Ask someone who didn’t build the field to update a representative page using only the instructions. Watch where they hesitate. If they ask what a field means, fix the label or the guidance. I’d rather rewrite a help line once than explain the same field in every training session.
Check the result in preview and on the published page. Confirm that the expected content appears, optional sections behave properly and links work. A field guide is not complete just because every field has a sentence beside it; the instructions should help a person publish correctly.
Keep the document near the workflow: a CMS help panel, editorial handbook or linked guide. Name an owner and review it when the template changes. If the field is renamed, removed or repurposed, update the explanation at the same time.
Keep the field model manageable
Documentation often reveals that the CMS has too many overlapping fields. If editors keep putting the same content in two places, ask whether the template or data model can be simpler. More fields don’t always mean more flexibility. Often they just mean more ways for pages to drift apart.
Include screenshots with care
A screenshot can show where the field appears, especially when a custom interface differs from the standard WordPress editor. Add a caption that explains what the editor should notice. Keep screenshots focused and avoid including private drafts, user details or browser tabs that reveal unrelated information.
The written instruction still needs to make sense if the interface changes. Use field labels and page names rather than relying on “the third box from the top”. When a plugin update changes the editor, check the guide and replace outdated images. If an editor cannot match the instructions to the screen, the documentation has already drifted.
For a group of fields, show the expected order only when order affects the published page. If fields can be rearranged safely, say that. Explain whether the editor should preview after changing them, and which part of the page to inspect. Good guidance connects the action in the CMS to its result on the site.
Related reading
- Planning editorial approvals for a multi-author WordPress site
- WooCommerce and WordPress: custom post types for product education
A useful custom field has a clear purpose, an understandable label and predictable output. Start small: pick the one field editors ask you about most, and write a single plain sentence of help text for it this week. Which WordPress field would your editors understand better with that one sentence beside it?