Create or Update a Help Center Article

Create customer-facing documentation that is accurate, discoverable, current, and easy to execute.

Base guidance on verified product behavior and authoritative sources—not on a single support response, assumption, memory, or workaround that merely appears correct.

Treat documentation as part of the product experience. Customers should be able to understand the problem, complete the task, recognize success, and recover from common failures without unnecessary support intervention.

1. Confirm the knowledge is ready for customer documentation

Establish the documentation subject before drafting.

Identify:

• the customer problem, question, symptom, or task;
• the verified answer, behavior, resolution, or workaround;
• affected product area;
• affected product version, plan, role, configuration, platform, or environment where relevant;
• intended audience;
• authoritative source;
• source owner;
• required reviewer;
• whether the guidance is expected to remain stable.

Use the strongest available evidence, such as:

• a complete resolved support case;
• approved product documentation;
• release notes;
• engineering or product confirmation;
• an authoritative internal specification;
• current product behavior verified in an approved environment;
• an approved workaround;
• an existing canonical help article.

Do not promote uncertain information into stable customer guidance.

If the answer is:

• disputed;
• incomplete;
• temporary;
• customer-specific;
• dependent on an unresolved bug;
• awaiting product confirmation;
• likely to change imminently,

prepare internal documentation or a clearly maintained known-issue draft instead.

Mark uncertainty, scope, ownership, and verification status explicitly.

2. Inspect the existing documentation landscape

Before creating a new article, search the existing help center and related customer documentation.

Search using:

• customer language;
• exact error messages;
• UI labels;
• official product terminology;
• common synonyms;
• alternate spellings;
• legacy terminology when customers may still use it;
• common task-oriented queries.

Determine whether the correct action is to:

• create a new article;
• update an existing canonical article;
• merge overlapping articles;
• cross-link related guidance;
• redirect outdated content;
• retire obsolete content;
• create or update a known-issue entry.

Prefer strengthening the canonical source over creating another article that competes with it.

When approved support or search analytics are available, use them to understand:

• how customers phrase the problem;
• unsuccessful search queries;
• recurring ticket language;
• article exits;
• low-helpfulness signals;
• missing terminology;
• common points of confusion.

Use those signals to improve findability and comprehension, not to expose customer information.

Never place private customer, employee, account, credential, token, internal-system, or other sensitive information into reusable customer-facing documentation.

3. Select the smallest useful article type

Choose the format that best matches the customer's need.

How-to

Use when the customer needs to complete a defined task.

Troubleshooting guide

Use when the customer has a symptom, failure state, or error and needs to diagnose or recover.

FAQ

Use when a recurring question has a concise, stable answer that does not require a full procedure.

Known issue

Use when a verified product problem exists and customers need current status, affected scope, and an approved workaround.

Reference

Use when customers need definitions, configuration details, supported behavior, limits, roles, permissions, or other factual product information.

Avoid turning a simple answer into an unnecessarily long guide.

4. Draft around the customer's task or symptom

Write from the customer's perspective.

Lead with what the customer is trying to accomplish or what they are experiencing.

Use:

• numbered steps for ordered procedures;
• bullets for choices, requirements, or alternatives;
• exact UI labels when useful;
• exact error text when it materially improves searchability;
• short sections with descriptive headings;
• screenshots or visual examples only when they materially reduce ambiguity and are current, safe, and approved.

Do not rely on internal terminology when customers use different language unless both terms are necessary for discoverability.

For procedural articles

Include, where applicable:

1. what the procedure accomplishes;
2. prerequisites;
3. required permissions, role, plan, platform, or configuration;
4. ordered steps;
5. expected result;
6. how the customer can confirm success;
7. the most relevant recovery or troubleshooting path;
8. related documentation.

Do not omit prerequisites that could cause the procedure to fail.

For troubleshooting articles

Include:

• symptom or error;
• affected conditions;
• likely causes when verified;
• diagnostic checks;
• recovery steps;
• expected result;
• escalation path when self-service recovery is not appropriate.

Order troubleshooting steps from safest and most likely to more invasive actions.

Clearly identify destructive, irreversible, security-sensitive, or data-affecting actions.

For known issues

Include:

• clear issue description;
• current verified status;
• affected scope;
• affected versions, plans, platforms, roles, or configurations when relevant;
• approved workaround, if one exists;
• limitations of the workaround;
• last verified date;
• where customers should look for updates when appropriate.

Do not promise a fix date, release, feature, SLA, compensation, or outcome unless it has been explicitly approved for customer communication.

5. Verify the article against current behavior

Treat verification as a required step.

Check the draft against the current product or another authoritative source.

When permitted, navigate the product in an approved test or demonstration environment to confirm:

• navigation path;
• exact UI labels;
• ordering of steps;
• permissions;
• roles;
• plan requirements;
• platform differences;
• configuration assumptions;
• resulting state;
• recovery behavior.

Use production customer accounts only when explicitly authorized and necessary.

Recheck:

• links;
• screenshots;
• commands or code snippets;
• error messages;
• terminology;
• role assumptions;
• plan assumptions;
• product-version assumptions;
• external dependencies;
• destructive or irreversible actions.

Do not claim verification that was not actually performed.

If the product cannot be checked directly, state which authoritative source was used and identify any remaining verification gap.

6. Validate safety, privacy, and permissions

Before customer publication, check whether the article includes actions involving:

• deleting data;
• changing permissions;
• changing billing;
• modifying authentication;
• rotating credentials;
• exposing logs;
• exporting data;
• changing security settings;
• disabling protections;
• irreversible configuration changes.

Make consequences clear before the customer reaches the risky step.

Never include:

• real credentials;
• private tokens;
• customer-specific identifiers;
• confidential internal URLs;
• private customer screenshots;
• unnecessary personal information;
• internal-only security procedures not approved for customers.

Use sanitized examples where examples are necessary.

7. Prepare the review package

Deliver the draft together with enough metadata for review and maintenance.

Include:

• proposed title;
• article type;
• intended audience;
• product area;
• help-center category;
• suggested search terms and synonyms;
• authoritative sources;
• last verified date;
• applicable product version or configuration;
• related existing articles;
• content proposed for update, merge, redirect, or retirement;
• unresolved questions;
• required reviewers.

Required reviewers may include, depending on the subject:

• Product;
• Engineering;
• Support;
• Customer Success;
• Legal;
• Security;
• Privacy;
• Billing or Finance;
• Brand or Communications.

Do not imply approval from a reviewer who has not approved the content.

8. Publish only through the correct approval path

Treat documentation lifecycle actions as separate states.

Examples include:

1. knowledge identified;
2. draft created;
3. draft verified;
4. reviewer approval obtained;
5. existing article edited;
6. new article created;
7. article published;
8. obsolete article archived or redirected;
9. customer-facing announcement made.

Approval of one state does not automatically authorize the next.

Follow the active scoped permissions for the exact:

• help-center workspace;
• collection or category;
• article;
• publication action.

Before modifying live content, confirm that the intended article and destination are correct.

After a write, update, archive, redirect, or publication action, verify the resulting state when the system allows it.

Never treat drafting permission as publishing permission.

9. Preserve canonical knowledge

After publication, keep the accepted article structure, source standards, terminology, ownership, and verification expectations available for future maintenance.

When multiple articles refer to the same behavior, maintain a clear canonical source and use cross-links where appropriate.

Avoid allowing duplicated guidance to diverge over time.

Record enough provenance to answer:

• what behavior this article documents;
• which source verified it;
• who owns the knowledge;
• when it was last verified;
• what product scope it applies to.

10. Maintain documentation without silently rewriting customer guidance

Documentation maintenance may be assisted by a recurring review workflow when the sources, ownership, permissions, and review process are stable.

Useful maintenance signals include:

• stale or broken links;
• changed UI labels;
• changed product behavior;
• new releases affecting documented steps;
• recurring support tickets;
• repeated unsuccessful searches;
• low-helpfulness signals;
• duplicate articles;
• screenshots that no longer match the product;
• outdated role, plan, or permission requirements.

A maintenance workflow should prepare proposed changes and supporting evidence for review.

It should not silently change published customer guidance unless explicit authority and review rules allow that behavior.

Stop automated maintenance and request human review when:

• authoritative sources conflict;
• current product behavior cannot be verified;
• the product change is ambiguous;
• permissions change;
• the workaround is no longer approved;
• legal, security, privacy, or billing implications appear;
• the canonical article cannot be identified reliably.