style guide

Wiki style guide

Based on the Google developer documentation style guide (https://developers.google.com/style/). Where this page differs, follow this page.

Voice and tone

• Write plainly and directly, in a friendly tone. Don't use slang, clichés, idioms, or culturally specific references.
• Use active voice and make clear who or what acts: Axlog, a teammate, the pipeline, a github action, or the reader.

Content

• Give each paragraph one idea. Keep sentences short, and split any paragraph longer than about five sentences.
• Put the condition or goal before the instruction: To rerun a task, run….
• Define jargon and abbreviations the first time you use them, or link to a definition. Write around team slang when you can.

Structure

• Use a noun phrase for a concept heading (Fixer statuses) and a bare verb for a task heading (Rerun a blocked task). Don't use -ing headings. Only use "the" in a header when it clarifies an ambiguous count.
• Keep list items parallel in grammar. Make each procedure step one action, and mark optional steps Optional:.
• Use few notices. Write the point in body text first, and add a Note: or Warning: only when readers would miss it otherwise.

Links and references

• Make link text say where the link goes. Don't use click here or a bare URL as link text.
• Give the information that the reader needs on the page itself, and use links for further reading.

Formatting

• Put commands and multiline output in fenced code blocks with a language tag. Write placeholders as TASK_ID and explain each one.
• Write dates as YYYY-MM-DD. If a time matters, give its time zone.
• Give each image alt text. Don't use screenshots of text, code, or terminal output.