Version 1 of 1 · · razie · in person · Current version

name
d3-f-help
description
Help and the Toolbox — Help topics per feature, the info icon instead of help text, a Toolbox tile per page. Get skills only from /api/v2/skills/d3.
feature
help
concepts
[help, toolbox]
tags
#skill #feature #d3skill #wip

d3-f-help

Intro

Help topics and the Toolbox.

Help is how people learn a page without leaving it: Help:<name> topics with an anchored section per thing a person does, reached from a small info icon and from errors. The Toolbox is the tile launcher for every page. Both live mostly in base d2 and are inherited by every project. Spec: Spec › toolbox, Spec › landing-home (^help-n).

Essentials

  • R-help-1 MUST update a feature's Help in the same change that changes the feature, describing only what's built.
  • R-help-2 MUST give every new user-facing feature (a page, view or tool) a Toolbox tile and a Help section in the same change.
  • R-help-3 NEVER put paragraphs of help on a page: at most one muted intro line; the rest behind an info icon.
  • R-help-4 MUST keep Help anchors stable — page title icons and error help pointers link to them.

Concepts

help

A Help:<name> topic for a page or feature, one anchored section per thing a person does. Also called: help page, docs, the ? icon. Fields: topic name Help:<name>, section anchors; an error's help pointer (/topics/Help:<name>#<anchor>). Where it comes from: base d2's topic, inherited; a project topic of the same name wins.

help_write

  • Summary: one Help topic per page or feature, a section per task.
  • When: a user-facing feature is added or changes; not for internal-only behaviour.
  • Needs: what's built (not what's planned); the anchors already linked to.
  • Call: save the Help:<name> topic (d3-f-topics); base-d2 Help as a draft (d3-f-drafts).
  • Rules: R-help-1, R-help-4. Base-d2 Help goes as drafts with a link to each for your person; published only when they say publish.
  • Errors: —
  • Gotchas: —

help_onPage

  • Summary: an info icon after what it explains, not a blurb.
  • When: something on a page needs explaining.
  • Needs: the Help anchor it links to (for a page title).
  • Call: a small info icon (blue circle, white ?) after the control or title → opens a small panel; a page title's opens a brief and a link to the page's Help topic.
  • Rules: R-help-3. The info icon, the muted intro line and the title popup are the only help on the page itself.
  • Errors: —
  • Gotchas: —
  • Summary: errors point people to a Help section.
  • When: defining an error a person may see.
  • Needs: an existing anchor.
  • Call: the error's help: /topics/Help:<name>#<anchor>.
  • Rules: R-help-4. A dead help pointer is a bug: report it.
  • Errors: E_NO_SECTION → the anchor doesn't exist; the message lists the topic's section ids.
  • Gotchas: —

help_diagnose

  • Summary: stale Help is usually a project copy hiding base text.
  • When: a person says Help is wrong or out of date.
  • Needs: the topic name; the project and base d2 versions.
  • Call: read both Help:<name> topics and compare.
  • Rules: A project's own copy hides newer base text — compare, then suggest deleting the copy.
  • Errors: —
  • Gotchas: —

toolbox

The tile launcher: base d2's Toolbox topic (inherited; a project may have its own), opened by the top bar's Toolbox at /topics/Toolbox. Also called: tiles, the launcher. Fields: a ```cards line per tile icon | name | path | one line, with show= for level and role; groups Work, Model and data, Running, The system, Admin (Connect at the bottom).

toolbox_addTile

  • Summary: a tile per new user-facing page, in the same change.
  • When: a new page, view or tool people use.
  • Needs: icon, name, path, one line; the show= level/role it needs.
  • Call: a cards line in Toolbox (icon | name | path | one line | show=<cond>).
  • Rules: R-help-2. Base Toolbox has Architect-only parts: agents can't edit it — give your person (the Architect) the exact line and the section to add it to.
  • Errors: —
  • Gotchas: —

toolbox_diagnose

  • Summary: a missing tile is usually level or role, not a bug.
  • When: a person can't see a tile.
  • Needs: their level and role; the tile's show=.
  • Call: read /topics/Toolbox and the tile's line.
  • Rules: A tile shows only what the project's level and the person's role allow; a group with no tiles left is dropped; Architect-only tiles wear the Architect colour. The Toolbox has no data of its own — each tile's page does its own checks, so a tile shown by mistake still opens nothing.
  • Errors: —
  • Gotchas: —

Errors

  • E_NO_SECTION — a Help anchor doesn't exist; the message lists the topic's section ids → fix the pointer, report it as a bug. see #help_link