Documentation Guideline

The HotWax Commerce Documentation Guidelines provide a a comprehensive framework for creating clear, consistent, and accessible documentation.

1. Document Structure

1.1. Title and Headers

All titles and headers should be written in “Title Case”
Title: Use a clear, concise title that accurately reflects the content.
Headers: Use hierarchical headers (H1, H2, H3) to organize content. Ensure headers are descriptive and help users navigate the document.

1.2. Table of Contents

The TOC should list all major sections and subsections.
Use headings to create a clear structure. This helps users with screen readers navigate the document.
When documenting on Gitbook, TOC is indexed on the right side. Make sure to use the correct heading levels. Use H1 for title, H2 for main sections, and H3 for subsections.

Learn more about Gitbook Headings

For example:

1.3. Sections and Subsections

Meta-Description: Add meta description with the following format on the top of the page:

---

description: >- HotWax Commerce's BOPIS fulfillment app enables retailers to efficiently manage Buy Online Pick-up In Store (BOPIS) functionality and handover store pick-up orders to customers.

---

Introduction: Brief overview of the document's purpose.
Main Content: Detailed information, instructions, and guidelines.
Conclusion: Summary of key points and any additional resources.

2. Formatting

2.1. Text Formatting

Bold: Use bold to highlight important terms or phrases.
Code: Use monospace font for code snippets, commands, and file names.

2.2. Lists

Bulleted Lists: Use for unordered lists.
Numbered Lists: Use for ordered lists or steps in a process.

2.3. Links

Internal Links: Use relative URLs for links within the same documentation.
External Links: Open external links in a new tab.

2.4. Tables

Use tables to present data clearly.
Ensure tables are responsive and accessible.

2.5. Images and Media

Images: Add images directly from the bottom of the GitHub markdown. Use high-quality images. Provide alternative text for accessibility.
Videos: Embed videos where necessary. Ensure they are properly captioned. Use the following format to embed YouTube videos:

{% embed url ="(Youtube URL)" %} caption {%endembed%}

2.6. Quotations

Double Quotes: Use “double quotations” when setting apart a word, quoting something, or using any title such as when documenting order status: “Created”, or “Approved”.
Backticks: Use backticks ( ` ) for highlighting actions. Such as when documenting a job name, application, or button.

3. Writing Style

3.1. Clarity and Conciseness

Use clear and concise language.
Avoid jargon and technical terms where possible. Provide definitions and examples where necessary.
Abbreviations
- Write abbreviations in full the first time they appear, followed by the abbreviation in parentheses. Use only the abbreviation thereafter.
- Example: Buy Online Return In Store (BORIS).

3.2. Active Voice

Use active voice instead of passive voice.
Example: “Install the app” instead of “The app should be installed.”

3.3. Consistency

Use markdown formatting. Learn more about Markdown here.
Maintain consistency in terminology, tone, and style throughout the document. You can refer to ChatGPT Prompts for consistency in the documents when using ChatGPT.
Use different types of hints to draw your reader’s attention to specific pieces of important information. Here’s markdown for different types of hints:

{% hint style="info" %} Add your content here { % endhint %}

{% hint style="success" %} Add your content here { % endhint %}

{% hint style="warning" %} Add your content here { % endhint %}

{%hint style="danger" %} Add your content here { % endhint %}

This markdown will look like this for hints:

Add your content here

3.4. Technical Content

Use Annotations: With annotations, you can add extra context to your words without breaking the reader’s train of thought. You can use them to explain the meaning of a word, insert extra information, and more. Readers can hover over the annotated text to show the annotation above the text.
Create an annotation: To create an , select the text you would like to annotate and click the Annotate option in the context menu. Once you’ve written your annotation, click outside of it to continue writing in the text block.