Use Claude to Draft Technical Docs from a GitHub README in 10 Minutes

You open a GitHub repository, finish reading its README, and still cannot tell what to install, which command to run, or how to recognize success. The developer knows the project. A newcomer needs a clear path through it. Technical documentation should close that gap.

Claude can help turn existing project files into a readable first draft in about 10 minutes, provided the scope is small and the source material is ready. Running the instructions, checking actual behavior, and getting a maintainer's review may take longer.

This guide focuses on a getting-started document. It includes reusable prompts, a verification process, and a way to maintain Vietnamese and English versions together.

🧭 1. Decide which document you need

“Write all the documentation for this repo” leaves too many decisions open. An end user wants to run the application, a contributor wants to change it, and an operator wants to deploy it. They need different instructions.

Define three things before asking Claude to write:

• Reader: a developer joining the project.
• Outcome: run the first example in a development environment.
• Scope: installation, configuration, startup, and troubleshooting supported by evidence.

GitHub's README guidance describes the README as a place to explain a project and help people get started. Keep the introduction concise there, then place a longer walkthrough in docs/.

A useful 10-minute target: a getting-started draft, a list of unresolved questions, and a test plan. Completion time depends on the project.

📂 2. Minutes 0–2: collect a focused source set

A README is a starting point, but it may be outdated or incomplete. Add files that directly answer the question: “What must a newcomer do to run this project?”

• README.md for the existing overview, instructions, and links.
• A dependency manifest such as package.json or pyproject.toml, depending on the project's stack.
• A dependency lockfile and runtime configuration, where available, to help check tooling and versions.
• .env.example for configuration names and sample values, rather than a real .env file containing credentials.
• Relevant entry points, usage examples, or tests to establish expected behavior.
• CI configuration, CONTRIBUTING.md, and LICENSE when those topics belong in the document.

Select files that support the agreed scope. A startup guide rarely needs every UI component, image asset, and unrelated module.

Record the branch and commit for the source set. These commands only read information from a local Git checkout:

git branch --show-current
git rev-parse HEAD

Include the commit identifier in your message so reviewers can tell which version the document describes. In a detached HEAD state, the first command may return no branch name; the commit is still useful.

🔗 3. Add the files and find the missing information

If GitHub integration is enabled for your account, use + → Add from GitHub and select the relevant files. Setup and access requirements are covered in Claude's official integration guide.

Alternatively, upload files or paste their contents in clearly labeled blocks. Whichever route you choose, ask Claude to list the files it actually read. Sending a URL does not establish that its contents were loaded.

Use minutes 2–4 to identify gaps before requesting a long draft. Replace the bracketed values in this prompt:

I need a getting-started guide for [target reader].
Outcome: [the specific task they should complete].
Scope: [included topics]; out of scope: [excluded topics].
Source: [repository], branch [branch], commit [commit ID].

Before writing:
1. List the files you actually read.
2. Summarize the startup process supported by those files.
3. Identify conflicts between the README, configuration, and code.
4. List missing information and the files needed to resolve it.

For commands, versions, environment variables, and APIs, identify
the supporting source file.
Do not guess missing facts; mark them [VERIFY].
Do not write the complete guide yet.

If the README names a command that has no corresponding script in the manifest, resolve that conflict first. Fluent prose cannot make an incorrect command work.

✍️ 4. Minutes 4–7: request a draft you can review

Once the input is sufficient, ask Claude to write in the order the reader will act. Each step should explain its purpose, the action, and the sign of success. If the expected result is not supported by the source, leave it marked for verification.

Using the supplied sources and resolved questions, draft
docs/GETTING_STARTED.md in English Markdown.

Structure:
- What the project does and who this guide is for.
- Prerequisites, with versions only where sources confirm them.
- Installation and configuration in execution order.
- Running the first example and recognizing a correct result.
- Evidence-backed troubleshooting: symptom, cause, resolution.
- Links to related documentation that already exists.

Rules:
- Preserve commands, paths, environment variables, and API names.
- Do not invent scripts, endpoints, configuration values, or output.
- Do not claim testing occurred without supplied test logs.
- Mark unsupported information [VERIFY].
- Clearly identify sample values as examples.
- Link to LICENSE if present; do not invent licensing permissions.

After the draft, return separately:
1. A map of important claims to supporting source files.
2. Questions that must be resolved before publication.
3. A verification plan starting from a clean environment.

Keep reviewer notes separate from the user-facing guide. A source map helps you audit the draft, but it does not necessarily belong in the final document.

💡 Make every instruction actionable

“Run the application after installation” forces the reader to guess. A useful instruction identifies the verified command, the working directory, required configuration, and a way to check that the application is ready.

Specificity should come from evidence. If the default port is unknown, do not let Claude fill in a familiar number just to finish the paragraph.

🔍 5. Minutes 7–10: review and plan the tests

Read the draft as someone who has never used the project. Look for skipped steps: must a database exist first, where do configuration values come from, and which directory are paths relative to?

Check the following areas. For a complex project, executing the tests can extend beyond the 10-minute drafting window:

• Commands and dependencies: do the commands exist, is the package manager correct, and are version requirements supported?
• Actual execution: follow the instructions in an appropriate environment and record results and failures.
• APIs and examples: compare function names, parameters, data types, and expected results with relevant code or specifications.
• Links: open each destination and confirm that the referenced file or section exists.
• Unresolved questions: resolve verification markers that affect the reader's ability to complete the task.

When a step fails, give Claude the command, working directory, sanitized error output, and relevant source files. Ask it to revise the affected section, then rerun the affected steps.

AI can draft quickly; actual execution determines whether the guide works. Do not mark a document as tested simply because Claude reread it and found it plausible.

🌐 6. Publish Vietnamese and English versions

Translate from a verified source document. Translating an unverified draft creates two versions of the same mistakes and doubles the cleanup work.

Translate the approved guide into [target language].
Preserve code blocks, commands, paths, filenames, environment
variables, API identifiers, and configuration values.
Preserve uncertainty: do not turn "may" into "always".
Do not add features, system requirements, or deployment steps.
List terminology that needs a reviewer's confirmation separately.

You can use docs/vi/ and docs/en/, or follow the project's existing structure. Check relative links after moving files: the same path can point somewhere different from a new directory.

For a visual walkthrough, record yourself following the approved instructions. CYAN CAM, currently in beta, supports screen recording and local MP4 output, which can help you prepare a companion tutorial. The video and written guide should describe the same application version.

🔄 7. Update the docs when the code changes

Put documentation changes on a separate branch and open a pull request for someone familiar with the project to review. Describe the scope, source commit, and steps you actually tested.

For the next update, give Claude the current document and relevant changed files or diffs. Ask it to identify affected sections before rewriting them: a renamed startup command, a new environment variable, or an API example that no longer matches the code.

Keep a short documentation check in the review process. Does the code change invalidate an instruction? Have translations been updated? Does the walkthrough need to be recorded again? This helps prevent a useful document from becoming stale after its first release.

✅ Start with one small task

Choose a repository you understand, its README, and one concrete reader goal. Draft a getting-started guide, then separate source-backed information from steps that still need execution. Once verified, apply the same process to configuration guides, API examples, or contribution instructions.

Claude helps you organize and explain faster. Documentation earns its value when another person can follow it and achieve the intended result.