Article Guidelines

Lab articles are durable handbook pages. They turn a useful signal, question, or research thread into a structured explanation that future learners can use without following the original conversation. Use this contribution type when the output should become a long-lived page about a concept, pattern, system, ecosystem area, or case study. A lab article is not a chat transcript, quick note, or loose source roundup. It should help a reader understand the topic, why it matters, how to reason about it, and where to go next.

​

Where articles belong

Choose the lane by topic, not by the source chapter that inspired the draft.

​

Issue and review flow

Create a GitHub issue before drafting the article. Use the Content Proposal form and choose Lab article or Major revision to an existing lab page. The core team reviews the issue first. They may approve the scope, ask for changes, or decline the proposal. After the issue is approved or acknowledged, the contributor can fork the repository and make the change. The core team then reviews the pull request separately. They may approve it, request revisions, or decline the PR. If the issue or PR is declined, the contributor can still keep their fork and reuse the work outside this repository.

​

Required shape

Every article should follow:

• the metadata contract in metadata-schema.mdx
• the structure in Article Template

Required sections:

• Summary
• Why It Matters
• Mental Model
• Architecture Diagram
• Tool Landscape
• Tradeoffs
• Citations
• Reading Extensions
• Update Log

​

Working rules

• Write in repo-native English.
• Use source inputs for concepts and citations, not as prose to preserve.
• Keep diagrams simple and repo-owned.
• Link to related lab pages so the article is part of the larger map.
• Keep the page durable. If a claim is likely to age fast, either verify it or write it in non-time-sensitive language.

​

Completion standard

An article is ready for review when it:

• fits the lane cleanly
• follows the metadata and section template
• cites its main sources
• avoids copied upstream teaching flow
• includes at least one useful internal reading link