End-User Documentation Guidelines

Purpose

This page defines the authoring standard for user-facing Pyle documentation.

Use this standard when the audience is:

• admin operators
• merchandisers
• customer service staff
• store managers
• business users configuring Pyle day to day

Do not use this format for developer-facing or system-reference pages. Those belong to the technical node documentation standard.

What This Doc Type Is For

End-user documentation should answer practical questions like:

• What is this feature for?
• When should I use it?
• Where do I find it in the admin?
• What steps do I take to use it?
• What effect will it have on the storefront or customer experience?
• What should I watch out for?

The goal is operational clarity, not implementation completeness.

Relationship To Technical Docs

For important nodes or domains, we should eventually support two parallel documentation layers:

1. Technical node dossier
   • for developers and AI agents
   • explains code structure, channels, integrations, and internal behavior
2. End-user usage guide
   • for non-technical Pyle users
   • explains purpose, setup, workflows, outcomes, and troubleshooting

The technical page is the research foundation. The end-user page is the practical usage layer built from that foundation.

Audience Rules

Assume the reader:

• does not know the codebase
• does not care about models, resources, observers, or actions
• wants plain language
• wants step-by-step usage guidance
• wants to understand business impact

Never make the reader translate technical concepts into business meaning.

Writing Rules

Every end-user page must:

• start with the business purpose
• explain when to use the feature
• describe where to find it in the admin
• state clearly when there is no dedicated packaged admin or storefront screen for the feature
• explain what changes in the storefront or downstream workflows
• use task-oriented language
• avoid code terms unless absolutely necessary
• call out limits, prerequisites, and common mistakes
• distinguish clearly between what the user can do directly and what happens automatically

Avoid:

• talking about models, controllers, traits, serializers, or migrations
• copying technical node pages into simpler wording
• listing internal implementation details that do not affect usage
• assuming the user understands platform architecture
• implying a direct UI workflow when the packaged product only exposes the feature indirectly

Evidence Standard

Even though the output is non-technical, the research still has to be evidence-backed.

Use sources in this order:

1. admin UI flows
2. storefront UI flows
3. API behavior only when it changes user workflows
4. import/export flows
5. ERP or sync behavior
6. framework code for confirmation of hidden rules or side effects

If a rule affects the user experience, confirm it in code before documenting it.

Required Page Structure

Every end-user page should use this structure:

# <Feature or Node Name>

## What This Is

## When You Would Use It

## Before You Start

## How To Use It In The Admin

## What It Changes In The Storefront

## Common Tasks

## Rules, Limits, And Things To Watch

## Troubleshooting

## Related Features

Allowed Variants

Concept page

Use when the main job is to explain what something is and why it exists.

Examples:

• Product Types
• Customer Groups
• Shipping Services

Task page

Use when the main job is to walk through a specific workflow.

Examples:

• How to create a product type
• How to restrict a shipping service by product type
• How to review vendor mappings

Settings page

Use when the main job is to explain a configurable area and its impact.

Examples:

• Promotion settings
• ERP bridge settings
• Maintenance settings

Section Expectations

What This Is

Explain:

• the feature in plain business language
• what business problem it solves
• what kind of user typically touches it

When You Would Use It

Explain:

• common situations where this feature matters
• when not to use it
• what it is often confused with

Before You Start

Explain prerequisites such as:

• permissions
• required setup
• related records that must exist first
• imports or syncs the user should be aware of

How To Use It In The Admin

This is the core task section.

Write it as operational steps:

1. where to navigate
2. what fields matter
3. what choices the user makes
4. how to save or confirm
5. what result to expect

Only include fields and actions the user can actually see or use.

If there is no dedicated packaged admin screen, say that directly and explain the nearest practical workflow the user actually uses instead.

What It Changes In The Storefront

Explain user-visible outcomes such as:

• what a shopper can see
• what becomes selectable or unavailable
• what pricing, shipping, eligibility, or display behavior changes

If nothing appears directly in the storefront, say that clearly.

Common Tasks

List 3 to 6 practical workflows such as:

• creating a new item
• editing an existing item
• disabling or removing it
• checking whether it is in effect
• importing it in bulk

Rules, Limits, And Things To Watch

Explain only the rules that matter to the user, such as:

• cannot delete while still in use
• some fields are managed elsewhere
• changes can affect other products or storefront behavior
• some updates only arrive through import or sync

Troubleshooting

Focus on practical issues:

• I changed this and nothing happened
• I cannot delete it
• I cannot see it in the storefront
• I cannot find the setting in the admin

Related Features

Point the user to adjacent concepts or workflows they may need next.

Question Set For Research

When researching an end-user page, answer these questions before writing:

• What would a non-technical user call this feature?
• What problem does it solve for them?
• Where would they expect to find it?
• What exact admin screens or dialogs do they use?
• Is there a real packaged screen for this feature, or is it only encountered indirectly through another workflow?
• What are the few fields or actions that matter most?
• What happens after they save a change?
• What changes in the storefront or customer experience?
• What common mistakes or misunderstandings are likely?
• What parts are direct user actions versus automatic system behavior?
• What related feature will they probably need next?

Source Formatting

Published end-user pages should not read like code notes.

If sources are included in the page, keep them light and repo-relative:

Sources:

- `packages/admin/src/Livewire/Admin/Settings/Types`
- `packages/framework/src/Http/Resources/Storefront/ProductResource.php`

Do not use absolute filesystem paths in published docs content.

Agent Prompt Standard

When delegating an end-user page to a sub-agent, require the agent to:

• follow this guideline exactly
• write for a non-technical Pyle user
• describe UI flows and business outcomes, not implementation internals
• confirm hidden rules in code before documenting them
• avoid editing unrelated files
• own one page at a time

Recommended Future Output Layout

For an important domain or node, the long-term documentation set should usually include:

• one technical node dossier
• one end-user usage page
• optional task pages for frequent workflows

Example:

• Product Type technical dossier
• Product Types end-user concept page
• How to create a product type task page