From user stories and tests to a rough user manual

AI-SAI-Generated Summary H-RHuman Reviewed H-EHuman Edited

I also wanted to use the testing work to draft user manuals. Stories gave me the task sequence and intent, tests provided executable steps and expected labels, and screenshots illustrated the screens. I could then review the draft and add the explanations readers needed.

The local guides describe how the documentation generator works with tests and screenshots to assemble draft content for review.

The inputs working together

        flowchart TD
    R[Recorded application workflow] --> U[Reviewed user stories]
    U --> T[Tests composed from existing helpers]
    C[Expected labels and options] --> T
    T --> E[Run tests and inspect results]
    E --> S[Named screenshots]
    U --> D[Draft manual structure and procedures]
    T --> D
    C --> D
    S --> D
    D --> H[Author review and application checks]
    H --> M[Manual for the selected application and role]
    

I used stories to plan the manual’s structure and procedures. The generator worked with screenshots and test files to assemble draft content.

Input	What it contributes	What I needed to review
User story	The task, ordering, feature, and intended documentation section.	Whether the story accurately describes the application and the reader’s goal.
Helper-based test	Concrete navigation and actions that can be exercised.	Whether the scenario covers the workflow and its important alternatives.
Configuration	Expected column labels, field names, and dropdown options.	Business definitions, permissions, and why a reader would choose an option.
Named screenshots	Images associated with steps and screens.	Whether the captured state is suitable and whether captions accurately explain it.
Execution output	Failures and diagnostics to investigate before relying on the captured workflow.	Whether required checks truly assert success; a screenshot alone is not a passing assertion.

Connect a story to its test

The refined Account story records a page type, spec filename, configuration reference, and intended documentation section:

## Proof of Address
<!-- page-type: table+detail | locked-test: account-proof-of-address.spec.ts -->
<!-- config: columnNames.ProofOfAddress -->
<!-- config-status: ok -->
<!-- doc-section: admin-manual/Account -->

These annotations are useful planning metadata. They describe how a workflow should connect to tests and documentation. The final filenames and screenshot destinations must be checked against the implementation; they do not always match the earlier story labels.

The full Proof of Address example contains these actual test calls. Their naming and folder behavior is explained in the screenshot walkthrough:

    test('View proof of address details', async () => {
        await clickViewActionInTable(page);
        await takeNamedScreenshot(page, 'proof_of_address', 'detail_view');
        await takeDocScreenshot(page, 'Investors', 'proof-of-address-view-details');
    });

The test names a user action, opens a detail view through a helper, and captures two consistently named assets. This gave me an action to describe and a screen to show in the manual.

What the documentation generator assembled

The generator guide describes grouping screenshots by feature prefix, analyzing corresponding tests to distinguish table pages from filter/download pages, generating Markdown page structures, and creating column-description stubs where appropriate.

The documented invocation for this feature is:

node _temp/generators/generate-docs-dynamic.js proof_of_address

The guide’s table-page output has the following shape:

_temp/generated-docs/
├── SectionName/
│   ├── section-name.md
│   ├── MainTable/
│   │   └── section-name-table.md
│   └── actions/
│       └── view-section-name.md
├── _static/citcorp_app/SectionName/
│   └── *.png
└── _data/
    └── columns_config_additions.json

The documentation workflow stores draft column definitions in columns_config_additions.json, later merged into source/_data/columns_config.json. These descriptions explain fields to readers; the test suite’s TypeScript columnNames export holds the labels tests look for. The draft descriptions and generated files still need review.

The suite also contains tooling that groups screenshot assets and writes a manifest for examples inside the test documentation. A separate verification step compares reference image names with screenshot calls, including fuzzy matching, to help identify coverage gaps.

A rough manual section from the tested workflow

The following is an illustrative manual draft, based on the final spec and configuration. It assumes the named image has been reviewed and copied to the asset location explained in named screenshots. It is not recovered generator output or a verified finished manual page.

# View Proof of Address details

1. Open Account → Proof of Address.
2. Use the Status filter to narrow the list when needed.
3. Use the record's View action to open its details.
4. Review the displayed information and history table.
5. Select Back to return to the list.

## Information shown

The detail checks identify these labels: Proof Of Address ID, Status,
Sponsor Organization, CIT Corporation, Offering, and Address.
The history table uses Date, Status, and Added By.

```{figure} /_static/citcorp_app/ProofOfAddress/proof_of_address_detail_view.png
:alt: Detail fields and history for a Proof of Address record

The selected record's detail screen, captured during the test workflow.
```

Author follow-up: explain the purpose of this workflow, who can access it,
what each status means, and what the reader should do next.

The illustration intentionally leaves business explanations as author follow-up because tests of visible labels cannot supply those definitions reliably.

How this supported different manuals

The reusable part was the process: understand the application, review its stories, exercise its workflows, capture named images, and assemble a draft. Selecting a different application or manual requires its own role, navigation, expected values, screenshots, and destination structure. A super-admin test does not establish what every reader is permitted to do.

The testing suite became a practical source for documentation drafts. We could combine user stories with readable test steps and named screenshots to assemble an initial manual for the application we were documenting. That reduced the repeated work of reconstructing the workflow and collecting its images. I could then focus on explaining the purpose, filling in business context, checking the intended audience, and reviewing the draft against the application.

When tests failed or screens changed, I could return to the agent repair loop, then review the affected manual steps and images before publishing.