Skip to content

STYLE_GUIDE.md

Latest commit

 

History

History
49 lines (34 loc) · 2.87 KB

STYLE_GUIDE.md

File metadata and controls

49 lines (34 loc) · 2.87 KB

Documentation Style Guide

This guide provides rules and best practices for all contributors to ensure the documentation is clear, consistent, and easy to maintain for both human and AI editors.

Tone of Voice

  • Audience: Address a professional audience of Oracle EBS users and developers.
  • Style: Use a direct, clear, and concise tone.
  • Voice: Use the active voice whenever possible. For example, write "Blitz Report generates the file" instead of "The file is generated by Blitz Report."

Formatting Rules

  • Headings: Use Markdown headings (#, ##, etc.) to structure content.

    • # Heading 1: Reserved for main document titles, such as in README.md or _coverpage.md.
    • ## Heading 2: The top-level heading for all other content files (e.g., ## 1. Creating a Blitz Report).
    • ### Heading 3 and #### Heading 4: Used for subsequent sub-sections.

  • Emphasis:

    • Use bold (**text**) for UI elements (e.g., Run button, Setup window) and for drawing strong attention to key phrases (e.g., "Basic steps are:").
    • Use inline code (`text`) for technical terms, filenames, parameter names, and values (e.g., part1_creating_report.md, n=n, :bind_variable).
    • Use italics (*text*) for general emphasis on a concept or for file paths.

  • Code Blocks: All code blocks must specify the language for syntax highlighting.

    • For SQL: ```sql
    • For Bash/Shell: ```bash

  • Admonitions: Use blockquotes with a note type for important information.

    • > **Note:** This is an important piece of information.
    • > **Warning:** This action can have critical consequences.

  • Tables: Use Markdown tables to present structured data, such as parameter descriptions or examples. Ensure headers are clear and content is aligned for readability.

Image Guidelines

  • Storage: Images are stored in a subdirectory named images within the guide they belong to.
    • User guide images go in /user_guide/images/.
    • Developer guide images go in /developer_guide/images/.
  • Naming: Use descriptive, kebab-case filenames (e.g., blitz-report-main-screen.png).
  • Alt Text: All images must have descriptive alternative text for accessibility. ![Descriptive alt text](./images/image-name.png)

Linking Policy

  • Internal Links: Always use relative paths for links between documents within this repository. For example, from a file in /developer_guide, a link to the user guide would be ../user_guide/README.md.
  • External Links: Use full, absolute URLs for links to external websites.

Source Attribution

If the content of a file is derived from an external source, add an attribution link at the very end of the file in italics.