Documentation Guideline
The HotWax Commerce Documentation Guidelines provide a a comprehensive framework for creating clear, consistent, and accessible documentation.
Last updated
The HotWax Commerce Documentation Guidelines provide a a comprehensive framework for creating clear, consistent, and accessible documentation.
Last updated
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. Make headers descriptive so that they help readers navigate the document.
Learn more about Gitbook Headings
# for Heading 1 ## for Heading 2 ### for Heading 3
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.
For example: GitBook Headings will appear on right side of documentation as TOC
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.
Bold: Use bold to highlight important terms or phrases.
Code: Use monospace font for code snippets, commands, and file names.
Numbered Lists: Use for ordered lists or steps in a process.
Bulleted Lists: Use for unordered lists.
Internal Links: Use relative URLs for links within the same documentation.
External Links: Open external links in a new tab.
Use tables to present data clearly.
Images: Add images directly from the bottom of the GitHub markdown. Use high-quality images. Provide alternative text for accessibility.
Images Names: All images should be named in a specific format which is lowercase and words should be separated by a hyphen ( - ), such as images-name
Videos: Embed drive videos where necessary and properly caption them. Copy the public-view Google Drive video link and use the following format to embed drive videos:
{% embed url ="(Google Drive URL)" %} caption {%endembed%}
Double Quotes: Use “double quotations” when 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` which will be shown as job name, application, button.
Use clear and concise language. Avoid jargon and technical terms where possible. Provide definitions and examples where necessary.
Content should flow naturally, shouldn’t feel heavy, or fluffy.
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).
Words that look like they were AI-generated should not be used repeatedly. Minimize the use of overly dramatic adjectives such as seamless, ensure, ensuring, crucial, essential, critical, game-changer, streamlined, comprehensive.
Use active voice instead of passive voice.
Example: “Install the app” instead of “The app should be installed.”
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
Add your content here
Add your content here
Add your content here
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.
Provide descriptive alt text for images.
All media should be accessible to readers.
Review and update documentation regularly to maintain accuracy.
Encourage feedback from users to improve the documentation.
BOPIS App
Fulfillment App
Pre-Orders App
Available to Promise App
Job Manager App
Order Routing App
Receiving App
Cycle Count App
Picking App
Import App
Users App
Facilities App
Company App
When writing the full name of an app, such as the Fulfillment App, "A" in "App" should be capitalized.
HotWax Commerce
Shopify (We write e-commerce as “eCommerce”)
Shopify POS
NetSuite
RetailPro
EasyPost