Skip to content

🧭 Methodology Guide: Mastering OctopiaSync Documentation

This file is not an example of content, but a strategic guide written in Markdown. It explains how to design, structure, and write the technical documentation for OctopiaSync to ensure it is professional, clear, and readily adopted by users.

🛑 The 3 Commandments of the Technical Writer

Before writing a single line of Markdown, keep this in mind:

  1. Think "User", not "Code": The user does not care how your PHP is structured. They want to know: "How do I press this button so my stock is updated on Octopia?".
  2. Be Actionable: A good documentation page must always end with a clear action (e.g., "Now, proceed to mapping").
  3. Image is King: A screenshot with a red circle around the button to click is worth 10 paragraphs of text.

🏗️ Typical SaaS Documentation Structure

Professional documentation must follow a logical path. Here is the recommended structure for OctopiaSync in your mkdocs.yml file: 

nav:
  - Home: index.md                  # Global vision, prerequisites.
  - 🚀 Quick Start:
    - Installation: install.md      # How to put the module on PS.
    - API Connection: api.md       # Authentication.
  - ⚙️ Core Configuration:
    - Category Mapping: mapping.md   # CRITICAL step.
    - Stock & Price Rules: stock.md # Business rules.
  - 🔄 Automation:
    - Cron Tasks: cron.md          # Automatic synchronization.
  - 📦 Daily Management:
    - Order Processing: orders.md   # How to handle fulfillment/shipping.
  - 🛠️ Troubleshooting:
    - Logs & Errors: debug.md       # Dépannage guide.

✍️ Writing a Page: The "B.A.R." Method

For every technical page, follow the B.A.R. method (Benefit, Action, Risk).

B - Benefit (Why read this page?)

From the introduction, explain what the user gains by configuring this section.

Example: "Category mapping automatically places your PrestaShop products into the correct Octopia aisles, guaranteeing their visibility."

A - Action (How to do it?)

Use numbered lists and code blocks to detail the steps.

Example: "1. Go to the Mapping tab. 2. Click 'Associate'."

R - Risk (What to check?)

Use admonitions to highlight common mistakes.

Example: "!!! danger 'Attention' Do not map an empty PrestaShop category."

🛠️ Markdown Tools to Master

MkDocs Material offers powerful tools. You must use them to rhythm your reading.

1. Admonitions (Visual alerts)

!!! info "Tip"
    Use this for a good practice.

!!! warning "Vigilance"
    Use this to avoid a minor bug.

!!! danger "Critical"
    Use this for an irreversible action (deletion).

2. Tabs

Indispensable for comparing versions or installation methods. 

=== "PrestaShop 1.7"
    PS 1.7 instructions...

=== "PrestaShop 8.x"
    PS 8 instructions...

3. Tables

The only clean way to list prerequisites or parameter definitions. 

| Parameter | Description | Type |
| :--- | :--- | :---: |
| `API_KEY` | Your secret Octopia key. | *String* |

📐 Page Finishing Check-list

Before considering a page "finished", check:

  • [ ] No Unexplained Jargon: If you use "Cron", briefly explain that it is a task scheduler.
  • [ ] One Screenshot: At least one image per major section.
  • [ ] A CTA (Call To Action) : A button at the end pointing to the next page.
  • [ ] Internal Links: Have you linked to the "Troubleshooting" page if there is a common error risk?

🆘 How to Troubleshoot the Docs

Problem Common Cause Solution
Broken rendering Missing empty line Add an empty line between the text and the element (table, list).
Empty tab Bad indentation Indent all content within the tab by 4 spaces or 1 tab.
Invisible icon Missing extension Verify that pymdownx.emoji is enabled in mkdocs.yml.