Document Writing Methodology

Arda uses the Diataxis framework to structure all technical and operational documentation. Every document is exactly one of four types. Never mix types within a single document.

Step 1: Choose the Document Type

Determine the type based on what the reader needs:

If the reader needs to…	Type	Structure
Learn by completing a task end-to-end	Tutorial	Introduction → Prerequisites → Steps → Summary
Get a fast, exact procedure (already has context)	How-to Guide	Purpose → Steps → Common Issues
Look up fields, limits, options, or API facts	Reference	Overview → Definitions → Specifications/Methods
Understand why/when/which, or needs mental models	Explanation	Introduction → Context → In-Depth Analysis

Step 2: Draft Using the Type Template

Tutorial

Tone: Encouraging, step-by-step, “learn by doing”
Structure: Introduction → Prerequisites → Steps → Summary
Rules: No deep theory. No exhaustive options. If the reader must choose among variants, link to Reference or Explanation.

How-to Guide

Tone: Direct, concise, outcome-oriented
Structure: Purpose → Steps → Common Issues
Rules: No teaching concepts. No narrating rationale. Task-focused only.

Reference

Tone: Neutral, complete, unopinionated
Structure: Overview → Definitions → Specifications/Methods
Rules: No how-to advice. No step-by-step guidance. Link out instead.

Explanation

Tone: Analytical, descriptive
Structure: Introduction → Context → In-Depth Analysis
Rules: No stepwise procedures. Keep it conceptual.

Step 3: Apply Global Rules

One type per document. Never mix. No step lists inside Reference. No theory in How-to.
Consistent structure. Use the headings specified for that type.
Markdown formatting. Clear headings, numbered steps where relevant, code blocks for commands and snippets.
Voice and readability. Target Flesch score approximately 80. Active voice. Minimal adverbs and buzzwords. Jargon is fine when it improves precision.
Cross-link. Add links to complementary document types (e.g., How-to links to Reference).

Step 4: Apply Arda Conventions

Domain lexicon: Use terms established in the technical documentation such as order card, Kanban loop, order mechanism, and scan-triggered workflow.
Workflow emphasis: Make physical-to-digital transitions explicit (e.g., scanning a QR code moves a card into the order cart and triggers downstream steps).
Tone: Calm, confident, never salesy. Precise and practical.

Step 5: Quality Review Checklist

Before publishing, verify:

Document clearly states and matches one Diataxis type
Headings, tone, and depth conform to that type’s template
Jargon is intentional; undefined terms are minimized or explained
Cross-links to complementary types are included
Language is clear, active, and scannable
Steps are numbered where applicable
No type-mixing (advice in Reference, steps in Explanation, theory in How-to)

Step 6: Save and Deliver

Save the document to the appropriate location in the technical documentation repository. Ask a reviewer to confirm placement before publishing.