The documentation only describes what Exowpee lets people do today. It is written for two readers at once: the business owner who wants to know what they can do, and the developer who calls the API. Every page starts from a situation the first reader recognizes and links to the reference the second reader needs.

​
Four kinds of page

Each kind of page has one job. Mixing them makes pages long and hard to use.
  • Topic page (Capabilities tab): everything you can do about one need, such as collecting customer credit. The reader has the need now and wants to solve it. The page opens with a short situation, then follows the reader’s steps and their variants.
  • Journey (Capabilities tab, Journeys group): one continuous story that crosses several topics from start to finish, such as opening a second shop. The reader follows it once to learn or to set things up. A journey that stays inside one topic belongs on the topic page instead.
  • API reference (API reference tab): one generated page per action, with every field, condition and effect. Nothing is written by hand there; it comes from the registry.
  • Concepts (Get started tab): why things work the way they do, such as spaces and permissions. Topic pages link to them instead of explaining again.

​
Topic page outline

  1. The situation, three to six sentences: a member of the cast, a concrete moment in their business, and the problem in their own words. No praise of Exowpee.
  2. One sentence that widens the scope, so that readers in other trades see themselves too, for example: “The same steps apply to any business that lets regular customers pay later.”
  3. Sections named after what the reader wants to do, in the order they meet those needs. Each one says what the person wants, then how Exowpee does it, with inline links to the actions. Follow the cast through the sections.
  4. At most one diagram, a Mermaid flowchart or state diagram, when it shows a flow or a change of state better than words.
  5. ## The rules: the product rules as a plain list, outside the story, so that a reader who skips the story still finds them.
  6. ## All the actions of this topic followed by <Actions />, the generated list, always last.

​
Journey outline

A journey follows one member of the cast from the first step to the last, in one continuous story. Each step says what they do and why at that moment, and links to the topic page that covers it in depth. The generated <JourneySteps /> block lists the actions in order.

​
Voice

  • English, plain words, short sentences. Readers may not be native English speakers.
  • The story is told in the present tense. Guidance speaks to the reader as “you”: “you may need to…, by doing…”.
  • No promotional words: not “powerful”, “seamless”, “simply” or “easy”, and no exclamation marks.
  • Lists for steps and options. Tables only for data with several attributes, such as fields.
  • Amounts in stories are written like “200,000 FCFA”. In the API, XOF has no decimal places.
  • Link an action by the address of its reference page: /reference/ followed by its route name without exowpee., each part in kebab-case and joined by /. A list action ends in /list, for example /reference/order/orders/list.
  • Product terms follow the glossary: company, organization, client account, agent account, cash register, and so on.
  • The story describes what people do, not API calls: “Sènami opens her register”, with the link on the action name, rather than “she calls the open endpoint”. Tokens, response shapes and field names belong to the API reference. When a reader needs one of them to use the feature, state it in the rules.

​
Truth

  • Every statement about what Exowpee does is checked in the code before it is written, including limits, refusals and side effects.
  • Names, amounts and limits in a story are examples. When a value could be taken for a default, say “for example”.
  • Never describe something the API does not do. Local rules (tax rates, invoice obligations, thresholds) appear only when the page documents the Exowpee feature that applies them, and the code confirms it.
  • A product rule is never stated only inside the story.
  • Describe what people can do and the rules they meet in normal use. Never describe how the data of other companies, organizations or client accounts is protected, how the API answers a request about them, or the internal mechanisms behind a rule (policies, gates, middleware, guards, scopes, indexes, soft deletes). State the rule itself: “a profile name must be unique in the company”, not how it is enforced.
  • Rules that apply to every action (a permission is needed, an inactive account or a call outside working hours is refused, a space must be selected) are explained once in the concepts pages. An action’s conditions list only what is specific to that action.
  • Use the words of the glossary. When a page needs a word the glossary does not define and a reader could stumble on, add it to the glossary first.
Before stating a rule, check:
  • Administrators: an administrator has every permission. That is said once, in Permissions explained, and nowhere else. Never describe what administrators cannot do or bypass.
  • Optional inputs: some checks run only when a field is sent. Say “when payments are sent” rather than stating the check as always true.
  • Uniqueness: read the unique index in the migration (it may be partial, for example pending or approved requests only), and whether soft-deleted rows still count.
  • Deletion: check whether the model uses soft deletes before writing that something is gone for good.
  • States: read the state machine before writing “permanently”, “for good” or “read-only”; many states can be left again.
  • Defaults: values filled before validation (prepareForValidation) are defaults worth documenting.
  • Replays: “calling again returns the same result” usually has exceptions, such as revocation or renewed credentials.
  • Statuses: never write that an action “always” answers a given status; validation and permissions can still refuse it.
  • Order of settlement: credit is settled by due date (the order’s own, or the customer’s), not by age.

​
The cast

One group of businesses and people serves the whole documentation, so readers meet familiar names and the details stay consistent. Pick whoever fits the situation. Keep their facts as written here, and add new people here before using them. No job is tied to a gender or to a region: owners, cashiers, drivers and accountants are men and women from the north and the south alike.

​
Illa Hardware, Cotonou

A hardware store in Akpakpa that sells cement, iron rods, roofing sheets and tools, with a warehouse behind the shop. It opens a second shop in Abomey-Calavi.
  • Madame Illa, the owner. She approves sales above her customers’ limits and checks the day’s figures in the evening.
  • Sènami Dossou, cashier at the Akpakpa shop.
  • Rodrigue Ahouansou, seller.
  • Bio Gounou, storekeeper at the warehouse.
  • Prudence Kiki, joins to run the Abomey-Calavi shop.
  • Michel Agossou, a mason who buys on credit for his building sites.
  • Ciments du Littoral, cement distributor that sells to Illa on 30-day credit.
  • Fers & Métaux du Port, iron rod importer near the port of Cotonou.
Fits: customer credit, cash registers and sessions, products sold by the bag or by the bar, suppliers on credit, second shop, staff access, transfers between the warehouse and the shops.

​
Pharmacie Bonne Santé, Parakou

A pharmacy with frequent internet cuts.
  • Dr Aminatou Chabi, pharmacist and owner.
  • Rachidi Yarou, cashier.
  • Bernadette Zannou, in charge of stock: lots, damaged goods, returns to the wholesaler.
  • Grossiste Pharma Nord, the wholesaler she buys from.
Fits: lots, stock levels, damaged stock, supplier returns, POS devices that keep selling offline, cash register computers.

​
Dépôt Houngbédji, Porto-Novo

A drinks depot that supplies bars and restaurants and delivers by tricycle and van.
  • Codjo Houngbédji, the owner.
  • Fifamè Sossou, manager and cashier.
  • Moussa Alassane, delivery driver.
  • Edwige Assogba, owner of the bar Le Palmier, a regular customer who sometimes pays by cheque.
  • Distribution Boissons du Sud, the depot’s main supplier.
Fits: crates and bottles as units of sale, bundles, delivery zones and deliveries, discount campaigns, cheques, customer credit for bars.

​
Groupe Gbaguidi, Cotonou, Parakou and Natitingou

A wholesale group with a company in each city, moving goods north by truck.
  • Sèdjro Gbaguidi, head of the group.
  • Orou Sabi, logistics manager in Parakou.
  • Mahougnon Tossou, the group’s accountant.
  • Gildas Akpovi, truck driver.
  • Gbaguidi Négoce Niger, a sister company in Niamey, owned by the same family and outside Exowpee, that buys goods from the Cotonou company.
Fits: organization and companies, roles per company, transfers with legs, vehicles, transport costs and losses in transit, reusable trips, money accounts, combined reports, analytics by site, related parties and transfer pricing.

​
Cabinet Hounkpatin, Cotonou

An accounting firm that keeps the books of small businesses.
  • Afiavi Hounkpatin, chartered accountant and head of the firm.
  • Comlan Adjovi, a trainee who works under one fixed profile with an agent account.
  • Boulangerie La Fournée in Bohicon and Akanni Transports in Porto-Novo, two of the firm’s clients.
Fits: client accounts, bookkeeping, entry imports, bank reconciliation, VAT declarations, period and year close, annual statements and their filing, sharing exports, agent accounts.

​
Local facts you can use

  • The currency is the CFA franc (XOF), with no decimal places.
  • Mobile money is widespread. MTN MoMo holds most accounts, followed by Moov Money and Celtiis Cash (ARCEP data reported by Osiris, 2023).
  • Dantokpa in Cotonou is one of the largest open-air markets in West Africa (Le Petit Journal).
  • Much of the traffic through the port of Cotonou continues to Niger and Nigeria (JICA).
Credit notebooks and the evening report to the owner are common practice but not documented in published sources. Use them as situations, not as facts.

​
Generating the reference and the lists

php artisan docs:sync rebuilds the API reference, the navigation and the generated lists from docs/registry. Run it by hand after editing the registry. It reads the routes and the database schema, so run it in Docker against a database migrated on your branch, with more memory than PHP’s default: docker compose exec app php -d memory_limit=1G artisan docs:sync. It never writes the registry and never overwrites a written page.
  • New action: add an entry to docs/registry/actions/<theme>.json, keyed by its route name. topic, title and summary are required. audience, permission, protections (its conditions), effects, also_in (other topics it is a step of) and irreversible are optional. Until it has an entry, the action is hidden from the reference and listed by the command.
  • Fields: describe them in docs/registry/fields/, or in the action entry (parameters, fields) for parameters and inline response fields. Names that mean the same thing everywhere have one description in the common section of taxonomy.json.
  • Request bodies come from Scramble. It cannot read the rules of a request that need the selected company or organization, so those actions show no body in the reference.
  • New topic or journey: add it to taxonomy.json. The command creates the page with its generated list; write the rest following this guide.
  • Topic or journey removed: move any text worth keeping, then delete its page.