toolkit

Scenario · The bigger jobs

Put this on the wiki

“Write this up somewhere the rest of us can find it.”

Writing something up for the team wiki usually stops one step short of actually happening, because the last step — copying markdown into a browser and dragging images in by hand — is tedious enough that it just doesn't get done. This publishes a local write-up along with its images directly to the wiki, checking first whether a page on the same topic already exists so the fix is an update rather than a third competing copy of the same information.

What to ask for

Wiki publisher (Outline)Publishes a local markdown file, with its local images, to a page on the team Outline wiki — the step other content tools stop short of, leaving a human to copy-paste markdown and drag images in by hand.

See it work

A real run of Wiki publisher (Outline):

$ node scripts/wiki-publisher-outline.mjs publish how-to-create-an-api-key.md --parent parent-uuid-1

plan — create "How to create an API key"  under Parent Doc
  images: 1 local ref(s), 0 missing

DRY RUN — nothing was written.
To apply: --apply

  report: ./out/wiki-publisher-outline-wiki-publisher-outline.html

$ node scripts/wiki-publisher-outline.mjs publish how-to-create-an-api-key.md --parent parent-uuid-1 --apply

plan — create "How to create an API key"  under Parent Doc
  images: 1 local ref(s), 0 missing

created http://<ip>/doc/how-to-create-an-api-key-doc-2
  1 image(s) uploaded · rollback: ./out/rollback.json
  report: ./out/wiki-publisher-outline-wiki-publisher-outline.html

The step that other content work stops one short of, leaving somebody to copy-paste markdown into a browser and drag images in by hand. That manual version is why write-ups do not happen.

  1. Check whether the page already exists. Search the wiki before writing. Updating an existing page is almost always the right move and it is the move nobody makes, because creating a new one is easier.
  2. Write it as a local markdown file with its images alongside. Relative image paths, in the same folder. This is also the reviewable form — a draft in a file can be read before it is anywhere public.
  3. Decide where it belongs. Which collection, and under which parent. A correct page nobody can find has the same value as no page.
  4. Publish as a dry run first. It uploads each image, rewrites the markdown to the uploaded URLs, and creates or updates the page. Dry run shows what it will do without doing it — including which images it found, which is where a broken relative path shows up.
  5. [manual] Apply once the preview is right, per the toolkit’s write-approval rules. Then open the published page and read it: image rewriting is the part most likely to look wrong, and it is only visible rendered.
  6. Link to it from wherever someone will actually be — the ticket, the sprint log, the related page. An unlinked wiki page is a private document with extra steps.

Update beats create

Step 1 is the only step here that is about restraint, and it is the one that decides whether the wiki stays useful. Every duplicate page splits the reader’s chance of finding the right answer and doubles the maintenance nobody signed up for.

What this does not cover

Whether it is worth writing up, and whether it duplicates a page that already exists. It publishes a local markdown file with its images to the wiki; it does not search for the page that already covers this, and a wiki with three pages on one subject is worse than a wiki with none. Nothing here reviews the content either — a published page carries whatever it said locally.

← All scenarios