0004: Authors and tags pages

Context#

People and topics are the two ways readers remember a decision when they do not remember its number: “the thing Marek wrote about Kafka”. The archive has that data in every record’s authors, deciders and tags. It should not require a second place to keep a list of people or an approved vocabulary of tags; such lists go stale the week after they are written.

Decision#

Inkan derives two directory pages from the front matter: /authors/ lists everyone named as an author or decider, /tags/ lists every tag in use. Both pages are indexes into the filterable record list: a name links to /decisions/?author=<handle>, a tag to /decisions/?tag=<tag>. An optional _authors.yml adds display names, teams, avatars and profile links, but is never required.

How to use it#

Authors#

Name people by handle in the front matter. The handle is the key used everywhere: filters, the authors page, avatars.

1
---
2
title: Use Stripe as the primary payment provider
3
authors: [piotr.nowak]
4
deciders: [tomasz.wojcik, anna.kowalska]
5
---

/authors/ then lists every handle that occurs in an authors or deciders list, plus everyone in _authors.yml, busiest first (by number of records, then by name). Each entry shows:

• the avatar: the avatar image from the directory, or initials built from the name;
• the name, linking to the pre-filtered index;
• the team, linking to the team page when it matches a project;
• N authored · M decided;
• a GitHub or GitLab profile link when the directory has one;
• the five newest records the person authored or signed off, with their status stickers;
• when there are more, a See N more records link to /decisions/?author=<handle>, which lists all of them.

To put names and teams behind the handles, add _authors.yml at the top of the content folder. See Optional author directory for the full format.

1
- id: anna.kowalska
2
  name: "Anna Kowalska"
3
  team: SRE
4
  github: akowalska
5
  avatar: https://example.com/avatars/anna.png
6
- id: marek
7
  name: "Marek Zieliński"
8
  team: Payments
9
  gitlab: mzielinski

A handle that is not in the directory still works everywhere: its name is the handle itself and its initials come from the handle (anna.kowalska becomes AK).

Tags#

Tags are free text in the front matter:

1
tags: [payments, vendor, pci]

A single value is accepted too (tags: payments). /tags/ shows every tag with its record count, most used first, as a tag cloud; each tag links to /decisions/?tag=<tag>. The same links appear on record headers, on the cards’ tag line and in the table view of the index.

There is no allow-list. If two spellings exist (postgres and postgresql) both appear, which makes the page a cheap way to spot drift.

Counts in the sidebar#

The sidebar hub shows “Authors” with the number of distinct handles across authors and deciders, and “Tags” with the number of distinct tags. Both numbers come from the records at build time.

Consequences#

• Nothing to maintain: a new author or tag appears on the next build, a removed one disappears.
• Without _authors.yml the pages show handles instead of names, which is fine for small teams and poor for a company-wide site.
• Tag spelling is not enforced. Reviewing /tags/ from time to time is the intended control.
• The authors page lists everyone in the directory even with zero records, which is useful as a staff list and noisy if the directory is large.
• A busy author does not stretch the page: each entry stays at five records however many the person has.
• ?author= matches deciders as well as authors, so the filtered index and the authors page agree on a person’s records. There is no filter for authors only.