Learn how to keep technical documentation synchronized with your codebase using IBM Bob's init command and a custom Docs Architect mode across real development scenarios — feature work, code reviews, onboarding, and ongoing maintenance.

Documentation is often treated as an afterthought in software development—something you do after the code is "done." But in practice, documentation needs to evolve continuously alongside your code. This tutorial shows you how AI code documentation actually works in a practical development workflow using IBM Bob.

Rather than focusing on theory, you'll see how to integrate Bob's documentation capabilities into your daily development process: from initial project setup through feature development, code reviews, and releases. You'll use the /init command to establish AI-readable context and create a custom Docs Architect mode that generates human-readable documentation at each stage of development.

What you accomplish

In this tutorial, you learn how to:

Set up AI code documentation as part of your development workflow

Use /init to create and maintain AI-readable project context

Build a custom Docs Architect mode for generating user-facing documentation

Integrate documentation updates into feature development cycles

Maintain documentation through code reviews and pull requests

Keep documentation synchronized with code changes in version control

Prerequisites

To complete this tutorial, you need the following:

Bob IDE installed.

A Git repository you want to document. Any local project or open source repository works.

How AI code documentation works in practice

Traditional documentation workflows separate writing code from writing docs. Developers write code, then (maybe) update documentation later. This creates a gap where documentation falls behind, becomes inaccurate, and eventually gets ignored.

IBM Bob is an IDE built to support the full software development lifecycle—and that includes AI code documentation. Bob makes documentation generation fast enough to happen alongside code changes, so docs stay current rather than falling behind. Here's how it works in practice:

The AI documentation workflow

AI learns your codebase: The /init command scans your repository and creates AGENTS.md files—structured summaries that serve as knowledge bases for the large language model

AI generates documentation: Custom modes like Docs Architect use this context to generate user-facing documentation (READMEs, guides, API docs)

You review and refine: AI-generated documentation is a starting point; you validate, edit, and commit it alongside code

AI stays synchronized: Re-running /init after code changes updates the AI's understanding, enabling quick documentation updates

This workflow integrates documentation into your development process rather than treating it as a separate task.

Real-world scenarios

This tutorial walks through practical scenarios you'll encounter:

Starting a new project: Setting up documentation from scratch

Adding a feature: Updating docs as you develop

Code review: Checking documentation in pull requests

Onboarding: Using AI-generated docs to help new team members

Maintenance: Keeping docs current as the codebase evolves

Scenario 1: Initial project documentation

You've inherited a repository with minimal documentation. New team members struggle to understand the codebase, and you need to create comprehensive documentation quickly.

Set up your workspace

Open the repository in IBM Bob IDE.
Open the Bob chat interface: Option + Command + B (macOS) or Ctrl + Alt + B (Windows)

Generate AI-readable context with /init

The first step is giving Bob knowledge about your project. Switch to Agent mode and run:

/init

Bob scans your repository and generates:

AGENTS.md in the repository root (main project context)
.bob/rules-code/AGENTS-code.md (Agent mode-specific context)
.bob/rules-plan/AGENTS-plan.md (Plan mode-specific context)s
.bob/rules-ask/AGENTS-ask.md (Ask mode-specific context)

These files contain:

Code structure and key directories
Technology stack and dependencies
Build, test, and lint commands
Code patterns and conventions

Why this matters: These AGENTS.md files serve as knowledge bases that Bob references in every conversation. Instead of re-analyzing your entire codebase each time, Bob has persistent context about your project.

Review the generated context

Open AGENTS.md and review what Bob discovered:

cat AGENTS.md

You'll see a structured summary of your project. If Bob missed important details (business rules, deployment conventions, team practices), edit AGENTS.md to add them. This file is meant to be customized.

Create a Docs Architect mode

Now create a custom mode that generates user-facing documentation. This mode will use the AGENTS.md context to create documentation for humans, not AI.

Click the settings icon in the Bob panel to open Settings.
Select the Modes tab.
Click the + icon to create a new mode.
Fill in the following values:

Field	Value
Name	Docs Architect
Slug	docs-architect
Role Definition	You are a documentation architect and writer who creates user-facing documentation. You work alongside AGENTS.md files (created by /init) which provide AI-readable technical context. Your role is to create human-readable documentation that complements, not duplicates, the AGENTS.md content. You focus on user needs: getting started guides, conceptual overviews, tutorials, and onboarding materials. Include code snippets with clear explanations. Add JSDoc comments (JavaScript) or Javadoc (Java) and docstrings where helpful to improve code quality.
When to use	Use this mode for writing and maintaining user-facing documentation such as READMEs, onboarding guides, and API docs. Not for writing or modifying application code.
Available Tools	Read, Edit

For the Mode-specific Custom Instructions field, copy and paste the following:

When documenting a project:
1. Review AGENTS.md files to understand project structure and technical details
2. Create user-facing documentation (READMEs, getting started guides, tutorials)
3. Avoid duplicating technical details from AGENTS.md (build commands, code patterns)
4. Focus on user workflows, conceptual overviews, and practical code examples
5. Include code blocks with clear explanations
6. Add docstrings and JSDoc comments to improve code quality

Generate:
- README.md explaining project purpose and navigation
- CONTRIBUTING.md with onboarding steps for new contributors
- Getting started guide with code snippets
- Conceptual documentation explaining architectural decisions

Click Save.

Bob creates a custom_modes.yaml file in .bob that contains the Docs Architect mode configuration. You can edit this file directly to make future changes.

Generate initial documentation

Switch to Docs Architect mode and prompt:

I've run /init to establish project context. Please create comprehensive documentation for this project:

1. Review AGENTS.md to understand the project structure
2. Create a README.md with:
   - Project overview and purpose
   - Quick start guide with code examples
   - Project structure explanation
   - Links to additional documentation
3. Create CONTRIBUTING.md with:
   - Development setup instructions
   - How to run tests
   - How to submit a pull request
   - Code style guidelines
4. Identify gaps in the codebase that need better documentation (missing docstrings, unclear functions)

Focus on making the technical details from AGENTS.md accessible to new developers.

Bob generates documentation files. Review them for accuracy, make edits, then commit:

git add AGENTS.md .bob/ README.md CONTRIBUTING.md
git commit -m "docs: initial project documentation with AI assistance"

Result: You've gone from minimal documentation to comprehensive docs in minutes, not hours.

Scenario 2: Documenting a new feature

You've just implemented a new feature. The code works, but your README, contributing guide, and API docs still describe the old state of the project. This is the most common point where documentation falls behind — the feature is done, but docs haven't caught up.

Here's how to close that gap using Bob.

Write the feature with Bob's help

While developing, switch to Agent mode so Bob can assist with the implementation. Because Bob already has project context from the /init you ran in Scenario 1, it understands your code structure, dependencies, and conventions — making its suggestions more relevant than starting from scratch.

Write the feature as you normally would, using Bob for code completion, refactoring, or asking questions about the existing codebase.

Re-run /init to update AI context

Once the feature is implemented, Bob's context is stale — it was generated before your new code existed. Update it:

/init

Bob rescans the repository and updates AGENTS.md to reflect what's changed — new modules, updated dependencies, and any new code patterns it detects.

Confirm the update captured your changes:

git diff AGENTS.md .bob/

If the diff shows your new feature, Bob is ready to generate accurate documentation. If something important is missing, edit AGENTS.md manually before continuing.

Generate documentation for the new feature

Now switch to Docs Architect mode. Because you've just updated AGENTS.md, Bob has an accurate picture of the new feature and can generate documentation that reflects the real implementation — not a guess.

Prompt Bob with what needs updating:

I've added a new feature to the project. Please update the documentation:

1. Add a section to README.md explaining:
   - What the feature does
   - How to configure and use it
   - A code snippet showing basic usage
2. Update CONTRIBUTING.md if the development workflow has changed
3. Create a dedicated docs page that covers:
   - How the feature works
   - Relevant API endpoints or interfaces
   - Code examples for common use cases
   - Code explanations for non-obvious logic
   - Troubleshooting tips

Include code blocks with clear explanations. Add docstrings to any functions that lack them.

Review the generated documentation for accuracy — check that code examples actually match your implementation — then commit everything together:

git add src/ AGENTS.md .bob/ README.md CONTRIBUTING.md docs/
git commit -m "feat: add [feature name] with documentation"

Result: Your feature and its documentation are developed together and committed in the same pull request.

Scenario 3: Code review with documentation checks

A team member submits a pull request that adds a new API endpoint. You need to ensure the documentation is updated.

Review the code changes

git diff main feature-branch

You see new API endpoints but no documentation updates.

Check if /init was run

git diff main feature-branch -- AGENTS.md .bob/

If there are no changes to AGENTS.md, the developer didn't run /init. Ask them to:

Run /init to update AI context
Use Docs Architect to update user-facing docs

Generate missing documentation

If you're reviewing the PR, you can generate the documentation yourself:

git checkout feature-branch

In Bob, run /init, then switch to Docs Architect mode:

I'm reviewing a pull request that adds new API endpoints. Please update the documentation:

1. Review the new endpoints in src/api/
2. Update README.md with a brief mention of the new endpoints
3. Update docs/api.md with:
   - Endpoint descriptions
   - Request/response examples with code blocks
   - Authentication requirements
   - Error codes
4. Add JSDoc comments to the endpoint handlers if missing

Focus on making the API easy to understand for other developers.

Commit the documentation updates:

git add AGENTS.md .bob/ README.md docs/api.md src/api/
git commit -m "docs: add documentation for new API endpoints"
git push

Result: Documentation is part of your code review process, not an afterthought.

Scenario 4: Onboarding a new team member

A new developer joins your team. They need to understand the codebase quickly.

Have them run /init

The new developer clones the repository and runs:

/init

Bob generates fresh AGENTS.md files that reflect the current state of the codebase. The new developer can now:

Read AGENTS.md to understand project structure
Read README.md for getting started instructions
Read CONTRIBUTING.md for development workflow

Use Ask mode for exploration

The new developer can use Bob's Ask mode to explore the codebase:

@src/auth Explain how authentication works in this project

@src/api What API endpoints are available and what do they do?

@tests How do I run tests for a specific module?

Bob answers using the context from AGENTS.md and the actual source code.

Generate personalized onboarding docs

If your project lacks onboarding documentation, use Docs Architect:

Create an onboarding guide for new developers joining this project:

1. Prerequisites (tools, accounts, access)
2. Initial setup steps with code blocks
3. How to run the project locally
4. How to run tests
5. Overview of the codebase structure
6. Common development tasks with examples
7. Where to find help

Make it practical and include code snippets for each step.

Result: New team members can get up to speed in hours instead of days.

Scenario 5: Maintaining documentation over time

Your project has been in development for months. Code has changed significantly, and documentation is starting to drift.

Detect documentation drift

Run /init to see what's changed:

/init

Review the diff:

git diff AGENTS.md .bob/

Large changes indicate significant code evolution. This is your signal that user-facing documentation needs updates.

Update documentation systematically

Use Docs Architect to refresh documentation:

I've run /init and noticed significant changes to the project structure. Please review and update the documentation:

1. Review AGENTS.md changes to understand what's different
2. Update README.md to reflect current project structure
3. Update CONTRIBUTING.md if development workflow has changed
4. Identify any new features that lack documentation
5. Remove documentation for deprecated features
6. Update code examples to match current API

Focus on accuracy—make sure documentation matches the current codebase.

Establish a maintenance schedule

Add documentation updates to your regular workflow:

Monthly: Run /init and review changes
Before releases: Update all documentation
After major refactors: Regenerate affected documentation
In code reviews: Check if /init was run and docs were updated

Automate drift detection (advanced)

For teams that want to enforce documentation hygiene in CI, add a pull request check that verifies AGENTS.md and .bob/ are up to date. The check would run /init against the branch, then fail if the output differs from what was committed — signaling that the developer forgot to update AI context before opening the PR. Pair this with the PR template checklist from the best practices section to make documentation updates a required part of your review process.

Result: Documentation stays synchronized with code through regular maintenance.

Best practices for AI code documentation workflows

Integrate /init into your development process

Make /init a regular part of your workflow:

Run it after adding new modules or features

Run it after major refactors

Run it before creating pull requests

Run it monthly for active projects

Commit AI context and user docs together

Always commit AGENTS.md files alongside user-facing documentation:

git add AGENTS.md .bob/ README.md docs/
git commit -m "docs: update for [feature/change]"

This keeps both layers synchronized in your version control system and makes your repository self-documenting for tools like Mintlify that generate API documentation from Markdown source files.

Treat AI-generated docs as drafts

AI-powered code documentation tools generate starting points, not final products. Always:

Review for accuracy

Check code examples work

Verify technical details

Adjust tone and style

Add context AI might miss

Use context mentions for precision

When updating specific parts of documentation, use @ mentions:

@src/auth @docs/authentication.md Update the authentication documentation to reflect the new OAuth flow

This helps Bob focus on relevant code and documentation.

Include documentation in code reviews

Add documentation checks to your pull request template:

## Documentation Checklist
- [ ] Ran `/init` to update AGENTS.md
- [ ] Updated README if user-facing changes
- [ ] Updated API docs if endpoints changed
- [ ] Added code examples for new features
- [ ] Verified all code snippets work

Maintain code quality with docstrings

Use Bob to add docstrings and JSDoc comments:

@src/api Review all functions in this directory and add JSDoc comments to any that lack them. Include parameter types, return types, and usage examples.

This improves both code quality and documentation.

Troubleshooting common scenarios

Documentation doesn't match the code

Problem: Generated documentation describes features that don't exist or misses recent changes.

Solution:

Run /init to update AI context

Review AGENTS.md changes to see what Bob detected

Regenerate affected documentation with Docs Architect

Manually verify code examples work

/init misses important context

Problem: AGENTS.md lacks project-specific details like business rules or deployment conventions.

Solution: Edit AGENTS.md manually to add context /init couldn't detect. This file is meant to be customized.

Documentation updates take too long

Problem: Regenerating documentation for large projects is time-consuming.

Solution: Use context mentions to update specific sections:

@docs/api.md @src/api/users.ts Update only the user API documentation to reflect the new endpoints

Team members forget to update docs

Problem: Pull requests lack documentation updates.

Solution:

Add documentation checks to PR template

Set up CI checks that verify /init was run

Make documentation review part of code review process

AI generates incorrect code examples

Problem: Code snippets in documentation don't work or use deprecated APIs.

Solution:

Always test generated code examples

Use context mentions to point Bob at current code: @src/api/current-implementation.ts

Update the Docs Architect mode instructions to emphasize accuracy

Next steps

You've learned how AI code documentation works in practice using IBM Bob. You've seen how to:

Integrate /init into your development workflow

Use custom modes to generate user-facing documentation

Maintain documentation through feature development and code reviews

Keep documentation synchronized with code changes

Apply this workflow to your projects

Start with /init: Run it on your current project

Create your mode: Customize Docs Architect for your team's needs

Document as you develop: Update docs alongside code changes

Review in PRs: Make documentation part of code review

Maintain regularly: Schedule monthly /init runs

Keep documentation synchronized with your codebase

On this page