use-cases/update-documentation.md +104 −0 added
1---
2name: Keep documentation up-to-date
3tagline: Use code and other sources to automate docs updates.
4summary: Use Codex to compare source code changes, public docs, release notes,
5 and PR context, then draft focused documentation updates with verification
6 steps before publishing.
7skills:
8 - token: github
9 url: https://github.com/openai/plugins/tree/main/plugins/github
10 description: Read issues, pull requests, comments, review threads, and failed
11 checks when GitHub is part of your bug intake.
12bestFor:
13 - Developer docs, READMEs, runbooks, examples, and migration notes that need
14 to track behavior that changes frequently.
15 - Teams that maintain documentation for a technical product.
16starterPrompt:
17 title: Update Docs From Source Changes
18 body: >-
19 Update the [product/feature] documentation based on the following sources:
20
21 - the changed source files in [this repo/source linked repo]
22
23 - the existing docs pages that mention a new behavior
24
25 - any linked issue, PR, release note, or public reference I provide below
26
27
28 Then:
29
30 - identify what is user-facing
31
32 - update only the docs that need to change
33
34 - keep unpublished roadmap, private customer details, and internal-only
35 context out of public docs
36
37 - preserve the existing docs structure, terminology, and cross-links
38
39 - run the docs checks that fit the change
40
41
42 Before finalizing, summarize what changed, what you verified, and any claims
43 you could not prove from trusted sources.
44
45
46 [link release notes or other references here]
47relatedLinks:
48 - label: Workflows
49 url: /codex/workflows
50---
51
52## Introduction
53
54Documentation is easiest to keep current when it is updated alongside source changes, not weeks later. Codex can inspect changed code, tests, release notes, linked issues, and pull request context, then draft a scoped docs update that matches the existing structure.
55
56Use this workflow for developer docs, README updates, changelog drafts, migration notes, runbooks, or anything else that needs to track behavior that changes frequently.
57
58## How to use
59
60
61
621. Start from the change you need to document.
63
64 Share the branch, pull request, commit, issue, or files. If the docs are public, say explicitly that unpublished roadmap, private customer details, and internal-only context should stay out.
65
662. Ask Codex to map the affected docs.
67
68 Have it search existing docs for feature names, config keys, commands, examples, and related terms before drafting.
69
703. Update the smallest useful docs surface.
71
72 Codex should preserve the current page structure, terminology, cross-links, and frontmatter. It should avoid broad rewrites when a precise note, example, or section update is enough.
73
744. Verify the changes.
75
76 Ask Codex to run formatting and docs checks that fit the repo, then summarize the evidence behind each user-facing claim.
77
78## What to give Codex
79
80| Source | Why it helps |
81| ------------------------------------ | -------------------------------------------------------------------------- |
82| Changed code and tests | Lets Codex analyze actual behavior to draft focused documentation updates. |
83| Public release notes or product docs | Helps Codex match public terminology, availability, and feature status. |
84| Pull request or issue context | Explains why the change happened and which user-facing behavior matters. |
85| Local docs checks | Gives Codex a concrete definition of done before the docs are published. |
86
87Adding more context such as public release notes lets Codex avoid including private context or updates that are not yet public.
88
89## Make the workflow repeatable
90
91For a repo-wide convention, add documentation expectations to [AGENTS.md](https://developers.openai.com/codex/guides/agents-md). For example:
92
93```md
94## Documentation
95
96- When user-facing behavior changes, check whether docs, examples, or changelogs need updates.
97- Public docs must only include public information or behavior visible in this repo.
98- Preserve existing terminology and frontmatter.
99- Run the docs formatting and build checks before final handoff.
100```
101
102If the process has more steps, turn it into a [skill](https://developers.openai.com/codex/skills) so future Codex threads can follow the same source-checking, drafting, and verification loop. See [Save workflows as skills](https://developers.openai.com/codex/use-cases/reusable-codex-skills) that shares more details on this pattern.
103
104You can also turn this workflow into a [thread automation](https://developers.openai.com/codex/app/automations#thread-automations) by asking Codex to run it on a schedule, asking to fetch all the recent PRs from GitHub to automatically keep docs up-to-date, for example on a weekly basis: