styleguide

Markdown formatting

General Guidelines

  1. Clarity and Precision: Write clear, concise, and easy-to-understand documentation.
  2. Consistent Structure: Follow a consistent format for all documents.
  3. Active Voice: Use an active voice to make the documentation more engaging.
  4. Target Audience: Tailor the content to the intended audience’s technical expertise.

Formatting Rules

  1. Headings:
    • Use # for main titles, ## for subsections, and ### for sub-subsections.
    • Capitalize the first letter of each word in headings.
  2. Lists:
    • Use - or * for unordered lists.
    • Use numbers for ordered lists.
  3. Code Blocks:
    • Use triple backticks (```) for code blocks.
    • Specify the language for syntax highlighting (e.g., ` ```javascript `).
  4. Links:
    • Use [Link Text](URL) for hyperlinks.
  5. Images:
    • Use ![Alt Text](URL) to include images.
  6. Emphasis:
    • Use *text* or _text_ for italics.
    • Use **text** for bold.
    • Use ~~text~~ for strikethrough.

Content Rules

  1. Overview:
    • Include a brief overview at the beginning of the document.
  2. Examples:
    • Provide examples where applicable.
  3. Definitions:
    • Define technical terms and acronyms.
  4. Consistency:
    • Use consistent terminology and naming conventions throughout.
  5. Versioning:
    • Indicate the version of the software or API the documentation covers.

Review Process

  1. Proofreading:
    • Ensure proper grammar and spelling.
  2. Technical Accuracy:
    • Verify the accuracy of all technical details.
  3. Feedback:
    • Seek feedback from peers or stakeholders before finalizing.

Updates

  1. Change Logs:
    • Maintain a changelog for updates to the documentation.
  2. Regular Review:
    • Periodically review and update the documentation to ensure relevance.

Tools

  1. Markdown Editors:
    • Use tools like VS Code, Obsidian, or Typora for editing.
  2. Version Control:
    • Use Git for tracking changes.
This site is open source. Improve this page.