Help management

Use Help management to create and organize the Help Content that users read and that Hex uses as source evidence. Saving an article changes Help Content in SQL. It does not silently rebuild the current Help Knowledge version.

Start here

1. Select an existing topic in Help Topics, or select Create Topic.
2. Edit its routing, title, and article body.
3. Select Save changes when you want to save only.
4. Select Save & update Hex knowledge when this article is ready for the current Help Knowledge version.
5. Open Help Knowledge to monitor the queued update and test the questions that users may ask.

Use Rebuild all on Help Knowledge instead of an article update when the compiler, knowledge schema, embedding model, vector dimensions, or retrieval contract changed.

Help Content quality requirements

A Help article is ready for users and Hex only when it gives a complete, Actualog-specific answer. Do not write a generic overview that could belong to any PIM system.

Every important article must contain the parts that match its purpose:

• Term or concept — explain what the term means in Actualog, why it exists, what it is not, and which related terms users often confuse with it.
• Business rule — describe the condition, the result, exceptions, and the role, company, category, plan, workflow state, or feature flag that changes the rule.
• Task — describe where to go, what must already be true, the exact UI labels to use, numbered steps, the expected result, and common blockers.
• Application page — describe what the page is for, who uses it, every important region, filters, counters, statuses, buttons, background jobs, success messages, and next actions.
• UI element — describe what the button, field, status, badge, or counter means, when it appears, and what changes if the user uses it.
• Troubleshooting — describe the symptom, likely causes, checks, repair action, and when the user needs administrator or support help.
• Commercial, legal, or policy content — describe the exact rule or limit, where it is configured, and the effective date or plan dependency when that matters.

Good Help Content contains facts in the visible article body. AI metadata can help Hex route a question, but it must never be the only place where an important rule is written.

For example, a good article about creating a category should answer:

• who can create or propose categories;
• whether the category is created by a company, an expert community, or Application Admin;
• which page or workspace is used;
• what fields and templates must be prepared;
• what approval or publication step follows;
• which Help and application-page links are safe to show.

Hex can combine several relevant Help articles in one answer. Write narrow task sections and clear related links so a question such as “How do I create a product with a category template?” can use the product task article, the Category article, and the Effective Template article together.

What the page shows

• Help Topics is the SQL topic hierarchy. Expand a topic to find children. Use the drag handle to change sibling order.
• Markdown Files counts exported or importable files across locales. A Markdown file is an interchange format; Hex does not read an edited local file until it is imported and saved as Help Content.
• Unique Slugs counts distinct Help URLs found in the Markdown library.
• Edit Help Topic contains the selected SQL record and its translations.
• Operations imports, exports, or cleans Help data in bulk. Review the selected locale and operation carefully before running a cleanup.

Topic identity and page links

The public Help link is based on the saved slug. Application-page links are emitted by Hex only when the controller/action pair is in the server-owned navigation registry.

Optional advanced Hex overrides

Hex answer guidance is below Topic Body and is collapsed by default. Normally, leave it closed. The Help Knowledge compiler reads the article and automatically infers narrow topics, definitions, key facts, aliases and likely user questions. It can also combine compatible evidence from related Help articles.

Application Admin does not need to maintain a manual question list for normal Help writing. Application Admin tests any real user question on Help Knowledge after an update.

Open the advanced section only when an intentional exact-routing or regression override is needed. The fields do not replace the article body and do not contain an answer by themselves. Canonical terms and exact aliases populate the SQL exact catalog that Hex checks before Azure Search.

Canonical term

Optionally enter an exact concept name that must select this article, such as Effective Template. A canonical term can belong to only one Help topic.

Use one precise concept, not a sentence or a list. The article title and compiler-generated topics remain searchable; this override is useful only when an exact product term must route differently.

Exact aliases

Optionally enter one exact alternative phrase per line, such as Category Template. Overrides have higher authority than aliases inferred during compilation, so add only phrases that genuinely mean the same concept.

The quality scan on Help Knowledge reports an alias that still routes to more than one topic. Resolve the ambiguity in Help management rather than relying on the answer model to guess.

Test questions

Optionally enter one regression question per line only when this Help topic must be the expected source. This is not the normal place to collect or test user questions.

Example:

What is effective template?

These stored questions are regression expectations. To investigate an answer, enter the question directly in Answer quality diagnostics on Help Knowledge. The diagnostic compares selected evidence and citations without asking the answer model to compose a response.

Writing a concise definition

For an article that defines a product term, add a short Key idea section containing the authoritative meaning. During compilation Actualog preserves the complete section as the topic summary, then stores each definition, fact, rule, example, or exception inside it as a separate typed answer unit. A Key idea is therefore not automatically counted as one definition or one key fact.

For a procedure, keep prerequisites, ordered steps, warnings, and the expected result explicit. The compiler can then create a complete Answer Article instead of turning general background into invented instructions.

Do not try to make every Help document match one future search record. During compilation, Actualog turns source meaning into verified claims, can combine compatible claims from related Help documents, and builds small complete Answer Articles for particular concepts, tasks, pages, policies, and questions. One source document may support several articles, and one article may cite several source documents.

Save changes

Save changes stores the topic and any advanced overrides. Hex continues using the active Help Knowledge version until an update succeeds.

Use this option while drafting several related articles, then run Update from Help changes once from Help Knowledge.

Save & update Hex knowledge

This command performs two operations in order:

1. saves the article;
2. queues Update from Help changes using the compiler profile of the active Help Knowledge version.

The current version remains available while the update runs. The newly saved article is used only after the update passes validation and switches automatically. The update expands the change through bounded semantic context and source dependencies, then recompiles and reindexes only affected claims and Answer Articles. Unchanged articles and cached vectors are reused.

If no active Help Knowledge version exists, the article is still saved but the update is rejected. Open Help Knowledge and run Rebuild all for the first build.

Only one Help Knowledge job can run at a time. When several articles are being edited together, save them first and queue one update after the last change.

Import and export

• Import from Markdown writes selected Markdown content into Help Content.
• Export to Markdown writes saved Help Content to the Markdown library.
• Export Help Index and Import Help Index move hierarchy/index metadata for the supported workflow.

An import can change many topics, so use Update from Help changes afterward. Actualog compares source hashes and recompiles affected semantic neighborhoods; normal edits do not require a full rebuild.

Check the result

On Help Knowledge:

1. confirm that Help changes pending becomes clear after a successful update;
2. run Answer quality diagnostics with a real question that a user may ask;
3. confirm the expected complete Answer Article, its primary Definition or Key idea claim, all required supporting claims, and the clickable citation;
4. ask Hex the same question to inspect the composed user answer.

The retrieval diagnostic stops before answer generation. Its semantic-vector option is off by default because enabling it explicitly calls the configured embedding model.

Related topics

• Help Knowledge
• Semantic Search