Writing Datagrok help pages

Mechanics (front matter, headings, links, images, admonitions, build) are in help/CLAUDE.md; language, capitalization, and punctuation in help/develop/help-pages/writing-style.md and word-list.md. This skill covers what to write, how to prove it, how to shape it, and how to hand it over. GIFs are filmed with the bdd-answer skill (grok-bdd guide) in its help mode: see section 5.

Companion files:

File	Read when
release.md	Updating the help for a release: finding what shipped, help vs community post
.claude/skills/bdd-answer/SKILL.md (another skill), section 4	Recording or replacing a GIF: help mode, what a help GIF shows, the step vocabulary, checks

1. Process

1. Find what exists before writing. Grep the help for the topic and list the pages and sections that cover it. Extend an existing page rather than create one. Don't create overview or workflow pages that restate other pages: the sidebar already links them. If the help already mentions a feature correctly, don't add detail the task doesn't ask for.
2. Propose the structure first: which pages and sections change, and where each fact will live. Wait for approval.
3. When the reviewer questions a section, answer with the evidence (is it new, is it covered elsewhere, what the code says) before changing or removing it.
4. Work in small, reviewable edits on a branch cut from the current master. help/ is a submodule of the datagrok-ai/help repository: branch, commit, and open the PR there, never commit the help pointer in public (a bot bumps it). Commit and push only when asked, with plain commit messages.
5. Finish with a reading list: for each topic, the page and anchor that now covers it.

Starting from a ticket

When the argument is a ticket, learn the feature from the ticket and the code before deciding what the help needs:

1. Read the ticket: description, comments, state, labels, linked tickets and PRs, and the parent epic with its other tickets: they set the scope.
   • GitHub issue: gh issue view <N> --repo datagrok-ai/public --comments (without gh: curl -s https://api.github.com/repos/datagrok-ai/public/issues/<N> and .../<N>/comments).
   • Jira ticket: the Atlassian MCP (getJiraIssue, instance reddata.atlassian.net). A linked GitHub issue, or a #<N>: prefix in the summary, is the one to cite.
2. Find the change: git log origin/master --grep="#<N>" (or --grep=GROK-<N>) in public, help, and core if you have access. Read the diffs, then the current code on master: commits after the ticket may have changed it. A ticket that asks for documentation or a docs review has no change: find the features it names by their UI labels in the code, and check each one as in the table in release.md.
3. Decide whether it belongs in the help: user-facing, finished, and released (see the table in release.md). Internal changes, unfinished work, and unreleased plugin versions get no help. Report the decision with the evidence.
4. Find the place: grep the help for the area and its UI labels, and check every page that repeats the same claim. Prefer updating the section that already covers the area. A help page that now says something wrong comes first.
5. Propose and wait for approval, then verify and write as in sections 2–6. End the commit message with the ticket: Help: … (GROK-<N>) or Help: … (#<N>).
6. Suggest a community post when the change is new and noticeable to users, changes existing results, or requires an action: one line in the reader's words, with the help page and anchor if there is one.

2. Verify every claim

• UI labels, menu paths, options, and defaults come from the code, quoted exactly as rendered. Read the code from the current master, not from a local working tree that may be behind.
  • A @Prop camelCase field renders as words (showMovingAverageLine → Show Moving Average Line). An explicit name: or caption: wins. The generated property tables use the field name and ignore name:, so don't copy labels from them.
  • Menu paths: the package function's top-menu, the viewer's context-menu code. When a page mentions one menu of a package, check all its paths on the page: stale paths travel together.
• Behaviour is checked in the running product before it is written: what a click does, what a dialog opens, whether a setting persists, what the result looks like. Permissions, sharing, and saving are checked with two accounts (author and recipient). Use the browser or a BDD feature run on the local stand (bdd-answer), and record what you observed.
• Numbers come from the data, not from assumptions.
• Released, finished, user-facing. Plugin changes under ## v.next in a CHANGELOG.md are not released. Ask before documenting a feature whose ticket is open; its developer may own the docs.
• When the UI offers several ways, describe the one in the place where the reader works with the object (where it is listed, found and applied), not the one that opens as a side effect. Check the other ways for bugs before choosing.
• A general mechanism is not a specific case. When the code has a mechanism for many objects, check that it applies to the one you write about (a connector of its own type is not covered).
• Carry the code's conditions into the text. When the code adds or shows something only under a condition (only the types found, only when several items exist), say so instead of "all".
• Never write an unverified claim as fact. Keep a list of claims checked only in the code or not checked at all, and show it. If a check is impossible, drop the claim.
• Bugs found on the way go to the reviewer as reproduction steps, not into the help. File a ticket only when the reviewer asks.
• Don't document legacy functionality or link to it. Ask when unsure.
• Clean up the stand: delete every entity you created, by id, and verify it's gone. Never save shared settings to try something out.
• Don't delete help files (stubs and drafts included) without the reviewer's agreement.

3. Terms and style

• Reuse the terms the help already uses (word-list.md): grep before introducing one.
• Bold is for UI elements the reader clicks or reads: buttons, menu items, fields, options. Concepts get plain text, or italics on first definition.
• Headings are 1–3 words in sentence case. Actions use gerunds ("Saving a dashboard"), consequences use "When …" ("When the source changes").
• Active voice, second person, one idea per sentence. Split sentences longer than about 25 words. No semicolons. No motivational sentences, no procedures for flows the UI makes obvious, no "best practices" lists unless every item is verified and actionable. When asked to rewrite, shorten: remove what the reader already knows.

4. Shaping the content

• Fix, don't rewrite. When a section is partly wrong, change only the wrong words. Keep the author's sentences, structure, and wording.
• Visible text states the rule and the recommendation. Supporting detail (comparison tables, long option lists, step-by-step procedures, worked examples) goes under <details><summary>How to use</summary>…</details> or another descriptive summary.
• Options are a list: * **Option**: what it does., not a table, unless the reader compares them by several criteria.
• A note inside a numbered step is indented to the step's text, so the numbering continues.
• No line starts with > when you wrap a menu path: Markdown turns it into a quote. Keep > **Item** on the previous line.
• Links in a list follow their neighbours (site URLs or relative paths).
• Short sections are prose, not bullets. Two links in a list become two sentences under a heading that says what they are.
• Every section has a heading. Text after an image without one reads as an orphan.
• Admonitions:
  • :::note for one exception to the rule just stated or a fact the reader would miss. At most two per section.
  • :::tip for advice the reader may skip.
  • :::warning and :::caution only for irreversible actions or data loss.
  • :::note developers for links to develop/ pages, JS API, or samples, phrased "You can do X".
• Link, don't repeat. If a page already explains something, write one sentence and link to it. Shared behaviour lives on one page (for example, regression and moving average lines on the scatterplot page), and other pages say what is theirs and link there.
• One link per concept, at the right place. Link the first mention and the next page the reader needs. Two concepts get two links to their own sections, never one link for both. No "see also" to pages one click away in the sidebar.
• Tables or prose. A table when the reader scans: options and meanings, formats, comparisons by several criteria, more than three rows people look up. Prose when it has two or three rows, full sentences in every cell, or only "what" and "why" columns. On concept and how-to pages a table is supporting detail under <details>; on reference pages it stays open.
• Keep the order of related sections the same across sibling pages (for viewers: trend lines, then formula lines and annotations). Don't restructure page templates unless asked.
• Tabs when content varies by context: variants or parts of one feature, each with its own GIF and short text (for example, Expressions / Exact match / Partial match in visualize/viewers/filters.md#expression-filter, regression line and moving average in visualize/viewers/line-chart.md). The full rule is in help/CLAUDE.md. A page with tabs needs mdx:\n format: mdx in the front matter and the Tabs / TabItem import block.
• No troubleshooting sections in reference pages. Non-obvious questions go to datagrok/resources/faq.md.
• Renaming a heading changes its anchor. Grep the whole help (release notes included) and js-api/src for the old anchor and fix every link.
• Headings the reviewer gives are used as given, after checking them against the code. Say so if one is inaccurate.

5. Images and GIFs

• Only where motion or layout matters: a new interaction or a multi-step flow. Static settings get none. One image per section at most. If the text says it all, remove the image.
• Next to the steps it shows. A GIF never goes in a section that explains a concept or a rule.
• Reuse an existing image by relative path instead of recording a duplicate. Don't add a GIF that shows what another GIF on the page already shows.
• Files go next to the page in img/, named by what they show. Every GIF has a -thumb.png of a meaningful frame next to it: in-app Context Help shows the thumbnail. Alt text describes the action. Delete images you replaced.

Recording a GIF

Load the bdd-answer skill and follow its section 4, "Help GIFs": the GIF is a BDD feature filmed in help mode, which also writes the thumbnail and puts both next to the page for review. The feature stays in the package's BDD suite, so the GIF stays true; it is committed to public, separately from the help change.

6. Check and hand over

1. Links: the build below fails on a broken link and warns on a broken anchor. Fix every link and anchor you broke. Report pre-existing breakage, and fix it only if the reviewer agrees.

2. Build: the local server and build commands are in help/CLAUDE.md. If the API docs fail to build locally (they need built libraries), save this as docusaurus/docusaurus.nodocs.config.js and delete it before committing:

   const config = require('./docusaurus.config.js');
   module.exports = {...config, plugins: config.plugins.filter((p) =>
     p[0] !== 'docusaurus-plugin-typedoc' && !(p[1] && p[1].id === 'api'))};
   

   Then, from docusaurus/: npx docusaurus start --port <free port> --config docusaurus.nodocs.config.js to review, and npx docusaurus build --config docusaurus.nodocs.config.js before merging. The build fails on broken links: with this config, links to /api are expected; everything else is real. Check which process holds a port before stopping anything, and never stop a process you didn't start.

3. Review table: page → sections changed → link to the anchor on localhost. Keep a running list of approved and pending pages. Re-open a page for review when you change it again.

4. Secrets: examples use placeholders (<password>, <token>). The repository runs gitleaks on every push, and .gitleaksignore entries are pinned to line numbers: adding lines above an ignored example breaks the ignore, so replace such values with placeholders instead.

5. Report: what was documented (page → section), what was left out and why, what was verified only in the code, bugs found (steps), and what is pending.