Writing checklist

Before pushing your changes to the remote branch, ensure you have completed the following checks.

Preliminary checks

• The document is previewed locally, and all content renders correctly.
• There are no broken links, missing images, or incorrect file references.
• The document follows the agreed-upon structure for content types:
  • How-to guides (Tasks): Step-by-step instructions for achieving a specific goal.
  • Concepts: Explanations of key ideas, technologies, or principles.
  • References: Detailed information about commands, configuration options, etc.
  • Tutorials: A guided learning experience, typically involving learning objectives and multiple steps.
  • Use cases (Examples): Practical applications or real-world scenarios demonstrating usage.

Style & structure

Headings & navigation

• No standalone headings (e.g., if a page has only one level 3 (###) heading, consider adding another or promoting it to level 2 (##) with better wording).
• Headings are meaningful and accurately represent their sections.
• Avoid deeply nested headings (level 4+ should be reconsidered).

Images & visuals

• Images are clear, properly formatted, and do not have distracting cursors.
• Text within images is not significantly larger or smaller than the surrounding body text.
• Screenshots reflect the correct UI language.
  • English is acceptable as a fallback if no localized (e.g., Chinese) version is available.
  • However, non-English screenshots should not replace English ones unless localization is explicitly required.
• Images and diagrams have appropriate alt text for accessibility.
• Image file names are descriptive and follow naming conventions.

Content & accuracy

Technical accuracy

• All steps, commands, and code snippets have been tested and verified.
• Configuration values, and file paths are accurate and up to date.
• Command-line instructions include expected outputs where relevant.
• There are no deprecated or outdated references (e.g., removed features).

Formatting & readability

• Code blocks use proper syntax highlighting.
• Lists and tables are structured properly to enhance readability.
• Important notes, warnings, and tips use appropriate callouts or formatting.
• Long paragraphs are broken into shorter, digestible sections.

Consistency & cross-referencing

• Terminology is consistent across sections and documents.
• Internal links between sections or documents are working and relevant.
• External references are valid, up to date, and use secure (https://) URLs.
• Acronyms and abbreviations are defined upon first use.