Design studies built on primary sources. Each one takes a concrete problem in a real codebase, works out from the code why the obvious answer is wrong, and produces a decision a stranger could audit.

articles/
  README.md          <- the map
  STANDARD.md        <- the rules
  TEMPLATE.md        <- the skeleton
  <category>/
    <slug>.md        <- English, the canonical file
    <slug>.ru.md     <- translation, structurally identical

One level of categories. Slugs name the subject, never the project or the issue number: the case an article is built on is metadata, not identity. STANDARD.md section 5 explains why that rule earns its keep.

A directory is created when its first article lands, not before. Categories with zero articles exist here as a taxonomy, so that a new piece has an obvious home and the collection does not drift into one folder per project.

Word and reading columns are English first, then the translation. The formula and the command to recompute both are in STANDARD.md section 5; they are stated per language because a Russian text of the same article is shorter in words and slower per word.

Status vocabulary: design (analysis only, nothing built), submitted (patch open upstream), merged, rejected, evergreen (not tied to a patch at all).

Edges use the fixed relation vocabulary from STANDARD.md section 7. Two rules: every edge is reciprocal, and every edge carries a reason. This table is where both are verified.

As the graph grows, keep it readable by preferring few strong edges to many weak ones. An edge that a reader would not actually follow is noise, and the Related section of an article is the first place a reader decides whether the collection is worth their time.

Target: the raprogramm-website repository, a Leptos 0.8 client-rendered app built with Trunk, routed by leptos_router, deployed to Firebase. The site carries a language enum (en, ru, ko, vi, zh, English as fallback), which is why the file naming in section 1 uses the same codes.

Status: built. The contract below is what the collection guarantees and what the site relies on; both sides now exist.

Nothing beyond writing in the forms of STANDARD.md section 10. A code citation is written the way it has always been written here, crates/foo/src/bar.rs:126-147 in backticks, and the code panel follows from it; there is no separate include, no snippet marker in the source repository and no second copy of the code in the article to keep aligned. An internal reference is written as the words section 2.6 or Appendix B.2 or C3, in Russian in any grammatical case, and the button follows from that. A figure is a file dropped beside the markdown and named relatively.

Two of these change what an article contains, not only how it looks. Because a reference arrives with the heading and the summary of its target, the sentence that used to remind the reader what section 2.6 established is now redundant, and so is every parenthetical re-explanation of a constraint. Cutting them is the cheapest length reduction available to an article of this genre, and it is the reason the checklist has a group for the reading surface. Because a citation opens the real lines at the pinned commit, a fenced block that merely repeats those lines is also redundant, and it was the more expensive of the two to keep honest.

Long articles with tables and fenced code are the whole content here, so the reading view is the product. Four things matter more than they will seem to at the time: word count and reading time shown on both the index card and the article header, taken from the frontmatter rather than computed in the browser; a table of contents built from the headings, because articles run past nine hundred lines; horizontal scrolling confined to code blocks and tables rather than the page; and a visible language switch on the article itself, since a translation is a sibling file and not a separate page.

The reading time is not decoration on a collection like this. An hour-long article with no stated length reads as a wall and gets closed; the same article labelled honestly, next to the twelve-minute path through it from section 0.2, gets started. Show both numbers wherever an article is listed.

1. Pick the category by the question the article answers, not by the technology it touches.
2. Copy TEMPLATE.md to <category>/<slug>.md and fill it in, deleting the instruction comments as each section is written. Write code citations, internal references and figures in the forms of STANDARD.md section 10 from the first draft: they are what the site turns into panels and buttons, and writing them right is what keeps the article from restating itself.
3. Write the English file to completion before starting any translation. A translation made from a moving original never converges.
4. Mirror it to <slug>.<lang>.md, then diff the headings of the two files to confirm structural parity.
5. Recompute words, code lines and reading time for each language with the command in STANDARD.md section 5, and write them into both the header block and the frontmatter.
6. Run the checklist in STANDARD.md section 8.
7. Add the article to the index in section 3 above, with its length columns, and its edges to the graph in section 4, checking that each new edge is reciprocated in the article on the other end.