Phoenix Docs

Diátaxis

Each page has one type. Do not mix types. Link to other types instead.

Before you write, identify the type with two questions: action or cognition? Study or work? Action + study = tutorial. Action + work = how-to. Cognition + work = reference. Cognition + study = explanation. If content does not fit the type, move it. Details: https://diataxis.fr/

ASD-STE100 (technical content)

Use for how-to guides and reference.

• One instruction per sentence. Max 20 words in procedures, 25 in descriptions.
• Use the imperative for instructions: "Set the variable."
• Use active voice. Use simple tenses.
• One word, one meaning. Use the same term for the same thing.
• Put conditions before the instruction: "If X, do Y."
• Write warnings before the step they apply to.
• No idioms, no "please", no "simply/just/easily".

Accessible images and videos

• Give informative images meaningful alt text that describes their purpose in the surrounding content. Inspect the image before describing it.
• For an image that is the only content of a link, describe the link's action or destination.
• Use alt="" for purely decorative images when nearby text already supplies their meaning. Do not use filenames as descriptions.
• Explain the essential information from complex diagrams in nearby text; alt text alone must not carry the full explanation.
• Give videos an accessible label and playback controls. Keep the demonstrated steps available in text, and provide captions for spoken audio.

Card images and page banners

Card art (<Card img>) and page banners (the image that opens a page) are generated, never hand-made.

• references/card-images.md: names, URLs, publishing to GCS and linking from MDX.
• references/card-design.md: the design language. Read it before you change how a card or banner looks.