Overview
A documentation generation run is a project job that creates a documentation version and reports its progress until it completes, fails, or is cancelled. Use this page when you need to start a run, monitor work already in progress, or decide what to do after the result appears.
| If you need to… | Go to |
|---|---|
| Prepare the project and choose run options | Before you start |
| Open the correct work surface | Find the work surface |
| Start a new run | Start a documentation generation run |
| Check progress or refresh job history | Monitor and manage a run |
| Respond to a status, empty state, or error | Handle status branches and errors |
| Continue after the run changes state | Know what happens next |
| Understand the Operations hub | Operations overview |
| Read each job status | Documentation job status reference |
| Follow the ordered generation stages | Documentation generation lifecycle |
Before you start
A project is the context for both starting a generation run and reviewing its jobs. Sign in before opening the project work surfaces. The project must have an identifier so you can open its jobs route, and the project information used by generation must already be saved.
Prerequisites
- Have a signed-in session with access to the project.
- Know the project to generate or monitor.
- Have the branch, optional version label, screenshot choice, video choice, and page limit ready if you need to change the run settings.
The generation form treats Version label and Max pages as optional. The choices for rebuilding, fixing findings, or capturing from the application appear only when the available preview reports pages. An unavailable Fix findings only or Capture from the app choice is disabled.
| If you want to… | Choose or provide… |
|---|---|
| Use a repository source | A value in Generate from or the selected branch |
| Identify this version later | A value in Version label |
| Limit the number of pages | A positive value in Max pages |
| Include updated page images | Include screenshots |
| Add narrated walkthroughs | Generate narrated videos |
| Choose how to generate | Select the generation method. |
Find the work surface
Operations is the hub for operational activity. A project's Activity & Jobs view is the project-specific place to monitor generation runs and refresh their history.
- Select Operations in the application navigation.
- Open the project's jobs route to reach Activity & Jobs.
- Select Configure & run documentation generation → when the jobs view shows that no generation runs exist and you need to move to project settings.
Result: The work surface is ready for either the project generation form or continued monitoring in the selected project's Activity & Jobs page.
While the Operations page is loading, it can show Loading operations….
The Operations surface can show these job-table headers:
| Timing and state | Work and output | Cost and detail |
|---|---|---|
| When, Status, Stage, Duration | Operation, Docs | Model, Calls, Tokens, Cost, Error |
Work from the headers and messages visible in your list.
Start a documentation generation run
A generation run starts work for the selected project and source. Choose the source and optional settings before committing the start action.
Prerequisites
- You are signed in and have opened the project generation form.
- The project information and source branch are available.
- The form is not loading and another generation is not already running.
Steps
-
Choose the source branch using one option from this table.
If you need to… Action Use the selected branch Enter the branch in Generate from. Choose another branch Select Select Another Branch, enter text in Search branches, then select the branch. -
Enter a value in Version label when you want to identify the new version.
-
Select Include screenshots to include updated screenshots.
-
Select Generate narrated videos to record narrated walkthrough videos.
-
Enter a positive page count in Max pages when you want to cap the number of pages.
-
Select one available generation option from this table.
If you need to… Select… Rebuild the documentation The available rebuild option Fix recorded findings The available fix option Include application content Capture from the app -
Select Generate to start the generation.
When the form is loading or a generation is already in progress, Generate is disabled. If the
start request fails, the error condition can show Failed to start generation.
Result: The generation form changes to its progress phase and shows the current stage and progress for the run.
Monitor and manage a run
Activity & Jobs is the project list of generation runs. An active run is a Running or Pending job with progress information; a Completed or Failed job can be expanded for its outcome or failure details.
Prerequisites
- You have opened the project's Activity & Jobs page.
- The project has loaded its job history.
Steps
- Read the status shown for each job row.
- Select Refresh in the page header to request the latest job history.
- Select Refresh job history in the Recent Jobs area when that control is available.
- Select a Completed or Failed job row to expand its details.
- Read the progress area on a Running or Pending job, including its stage and percentage.
The page can show Loading runs… while the first list request is in progress. A project with no
jobs shows No generation runs yet.
Every documentation generation run for this project lands here.
Result: The page shows the latest available job history, and an expanded row or progress area shows the information for the run you selected.
Handle status branches and errors
Each job status changes which operation is available. Use the status and the exact message on screen to choose the safe next action.
| What you see | What to do |
|---|---|
| A Running or Pending job | Select Cancel once. The control changes to Are you sure?; select it only when you intend to cancel the run. |
| A completed, failed, or cancelled job with generated documents | Select Delete N Docs once, then select Confirm Delete? only when you intend to remove those documents. |
| A completed, failed, or cancelled job without generated documents | Select Delete Job once, then select Confirm Delete? only when you intend to remove the job. |
| An error phase with a retry option | Select Retry Generation to return to the configuration phase. |
Version Generated! | Review the document and category counts, then continue to the project's versions. |
Generation was cancelled | Treat the run as cancelled and return to configuration or start a separate run. |
Job Failed | Read the failure details in the expanded row before choosing a recovery action. |
Jobs failed to load. | Check the project jobs page again. |
Failed to load job history: {error.message} | Select Refresh job history to request the history again; read the changing error details after the prefix. |
Showing the last successful load — refreshing failed ({error.message}). | Continue using the displayed rows, then select Refresh job history again; read the changing error details in parentheses. |
Operations failed to load. | Return to Operations and reload the operational surface. |
Insights failed to load. | Continue with job monitoring; the insights area is separate from the job list. |
| Queues are absent or unavailable | Continue with the job tables and status rows that are present. |
| Needs-attention data is absent | Continue with the available Operations sections. |
| Manual insights has no project selector | Use the currently selected project. |
Result: You have either kept the run available for monitoring, returned it to configuration, or completed the status-specific action shown on screen.
Know what happens next
The completion phase is the handover from generation work to version review. It shows the document and category counts for the generated version. An active run remains available in Activity & Jobs for continued monitoring.
After Version Generated!, open the project's versions to review the new version. Use
Documentation job status reference when you need the
meaning of a status, and Documentation generation lifecycle
when you need the ordered stages.
Result: You know whether to review the project's versions, continue monitoring Activity & Jobs, or use the status and lifecycle reference pages.
Was this page helpful?