Beginner's Guide to Authoring Topics with Codex

This track is for people who need to create or update service documentation, but do not feel fluent in GitHub, Markdown, or pull requests yet.

The goal is not to turn you into a Markdown expert. The goal is to give you a simple workspace where you can:

• keep the docs site open in a local browser preview
• use VS Code as the place where files, terminal output, and Codex live together
• tell Codex what you want in plain English
• paste notes, alarm text, screenshots, or rough troubleshooting details into Codex
• ask Codex to create the branch, edit the topic, run checks, push the branch, and help prepare the pull request

Use Tips and tricks when something feels stuck, when you want beginner-friendly workflow shortcuts, or when you want examples of how to use Codex for screenshots and PR fixes.

Note

Codex helps with structure, Markdown, MDX, Git commands, and repository conventions. For a new guide, create a PR with the information available and assign the relevant FSE from Technical Contacts by System. The FSE completes the draft and takes it through TW/SE2 review and merge. For an existing-guide edit, you remain responsible for the proposed content and review follow-through. See Guide ownership and workflow for both workflows.

Learn the authoring loop

You do not need to memorize Markdown syntax before you start. You do not need to memorize Git commands before you start.

You do need to learn the authoring loop:

1. Start from updated main.
2. Create a branch.
3. Ask Codex to make the change.
4. Review the rendered page locally.
5. Ask Codex to fix what looks wrong.
6. Run checks.
7. Push and open a pull request.

How to use this training

Work through these pages in order the first time you contribute:

Use Guide authoring workflow checklist after you have worked through the full training once and want a shorter repeatable path from branch setup to review.

1. Set up your workspace - install the tools and open the repo in the same basic setup used for docs authoring.
2. Start the local preview - run the local docs site and keep the browser preview open while you work.
3. Start each change safely - ask Codex to update main, create a branch, and stop before editing if anything looks risky.
4. Author with Codex - give Codex the content, screenshots, and plain-English instructions it needs to draft, preview, and fix a topic.
5. Prepare the pull request - ask Codex to summarize the diff, run checks, push the branch, and help create the pull request.

Use the appendices only when you need them:

• Appendix A - Mac setup
• Appendix B - Windows setup
• Appendix C - Drafting with ChatGPT
• Appendix D - Check GitHub access
• Appendix E - Use zdex from Slack

After this track, use the Author Guide to learn the service-docs-specific parts of topic structure, troubleshooting flow, software version logic, telemetry steps, and review expectations.