AI documentation with IBM Bob

In this tutorial, you’ll learn how to use IBM Bob as a documentation architect to analyze and document an existing GitHub repository. We’ll create a custom docs architect mode that reviews repository structure and code quality, identifies documentation gaps and produces detailed artifacts in the form of documentation-focused files. 

The result is an AI documentation companion that handles the tedious work of repository analysis and content organization, making documentation overhauls easier to plan and execute. It produces implementation steps, templates and draft documentation files that make it easier to turn documentation improvements into practice.

This guide is for developers, technical writers and teams looking to use an AI documentation tool in their IDE to analyze, organize and document fast-growing or fragmented repositories.

Creating and maintaining project and API documentation is challenging. This challenge is especially true for repositories that expose internal or public APIs, where behavior, inputs, outputs and dependencies are often defined only in code files. Sometimes these repositories span across several programming languages written by multiple contributors. Code changes frequently, repositories grow fast, and tracking features and modules becomes time-consuming.

Bob runs on large language models (LLMs), AI models that excel at processing natural language, and work directly in your IDE, by using the project files you’re actively working with to generate documentation that reflects the current state of the repository. It produces deliverables like readme files, contribution guidelines and structured documentation drafts or templates that can be refined and committed directly alongside your code.

Bob can also suggest implementation steps, providing guidance throughout the documentation process. This guidance is particularly valuable when working with legacy code that lacks consistent documentation.

Customizable modes allow your team to define Bob’s behavior and set clear goals based on your documentation needs. By streamlining the process, Bob helps maintain accuracy, manage scope and keep documentation up to date as projects evolve.

• IBM Bob IDE installed. Sign up for early access to Bob.

Follow the steps here or on GitHub by checking out our repository.

Open the IBM Bob IDE and take a moment to familiarize yourself with its layout. Bob is built on VS Code, so standard editor features and workflows apply.

Clone your repository in the IBM Bob IDE and set it as your working directory to begin organizing and documenting your codebase. 

If you don’t have a specific repo, you can also apply this step on any sample code or open source project.

Bob features specialized purpose-built modes that optimize behavior for various development scenarios. You can also build a custom mode to tailor Bob’s behavior for specific tasks and workflows. In this step, we’re going to create a custom “docs architect” mode.

Custom modes can be global or project-specific, allowing you to optimize specialized modes and experiment with different configurations to find what is best for your needs.

Create a custom mode through the mode settings menu or manually by editing the configuration files. We’ll walk through how to create a custom mode easily through the settings UI by navigating to the mode settings.

You can open the mode settings menu by clicking on the three dots at the upper right of Bob’s chat window and choosing “Modes.” Another route is by clicking on the mode-picker dropdown menu at the lower left of the chat window, and clicking the “gear” icon labeled “Mode Settings.” 

Once the mode settings are open, click the “+” icon labeled “Create new mode” to start inputting its configurations.

Modes have several components that are configurable as seen in the create new mode pop-up:

For reorganizing and documenting a GitHub repository, we’ll create a specialized custom mode that is tailored to analyze its contents and produce accurate documentation and suggestions for improvement.

Fill out the required components to create the new mode. First, give it a name that fits its purpose, “Docs Architect” suits the goal in this tutorial.

Next, enter the “Slug” that is used in URLs and file names. It must be lowercase and contain only letters, numbers and hyphens (for example, “docs-architect”). Bob will suggest a slug based on the name, but you can edit it.

The last required component is to add a description that defines Bob’s expertise and personality inside “Role Definition.”

For example: 

The role definition defines Bob’s core identity while using the mode. The more specific your description, the more likely your intentions will be met. Bob adds the details to the docs, including examples in code comments, docstrings and code snippets.

Back in the mode settings, you can also add a brief description to label the new mode for easier selection. This feature is nice when working in teams so that they know what your custom mode does at a glance, especially if this is a global mode. For our docs architect, “Reorganize and improve documentation for a project” does the job.

This is what the docs architect looks like fully configured:

Click “Create Mode” to finalize this step. You can go back and edit your custom mode at any time.

The next step is to actually ask Bob to document your project. Like with any AI, the quality of your prompt directly affects the quality of the response. When writing a prompt, be specific and clear, provide examples when possible and refine it using the Enhance Prompt feature to automatically improve your query with more context and structure by clicking the sparkle icon in the chat interface.

Try out the following prompt. Feel free to modify it to suit your outcomes:

This prompt works well because it clearly defines the scope and breaks the work up into discrete tasks. You can also enhance it further it by using the Enhance prompt capability. Once submitted, Bob will analyze the repository and generate documentation artifacts by using the docs architect mode role definition.

Bob prompts you for approval before reading, writing or modifying files or executing a command (for example, saving a file). For security, you can approve or deny the actions as prompted. Bob will likely ask for your approval several times during the execution of this task.

Documentation generation begins after Bob creates a to-do list of tasks that you can edit or approve.

This list outlines the entire list of actions that Bob will follow to complete your request.

Once the task is complete, Bob responds with a structured set of deliverables, not just a single wall of text. For example, Bob can produce:

• An analysis and inventory of the repository’s projects, modules or major folders
• Logical groupings based on functionality, technology or use case
• A proposed repository or folder structure to improve navigation
• Draft documentation files that are ready for review and iteration
• Implementation suggestions for next steps to make these changes production-ready 

These outputs are immediately actionable drafts that accelerate analysis and automate tedious documentation tasks. Many of these generated files are in Markdown, making it simple to preview, edit and maintain. You’ll still need to validate accuracy and make adjustments according to what aligns with your team and product priorities.

You might also notice in the chat window that Bob updates the actions completed in the task list and provides a comprehensive summary of what was delivered. 

This feature is useful when reviewing the generated content because it provides transparency to Bob’s workflow with summarizations about each deliverable.

One of the biggest advantages of using an AI assistant like Bob is how fast you can iterate. Bob uses multiturn conversations, meaning it maintains context throughout your conversation. You can ask Bob to refine a specific document (for example, just the readme files), request alternative structures or regenerate outputs after feedback from your team.

Use Bob in your technical documentation to capture Python dependencies, add comments on JavaScript code and update examples in real-time. Because the assistant already understands the repository structure, follow-up prompts are significantly faster than starting from scratch. As you iterate, Bob can suggest improvements such as reorganizing sections, updating code comments or refactoring documentation for clarity and consistency.

Once reviewed, the generated artifacts can be committed directly to the repository, shared internally for discussion or incrementally adopted overtime.

IBM Bob can quickly generate documentation artifacts and implementation suggestions, but, like any AI tool, not every output will perfectly align with your team’s needs or standards. Some sections might require refinement, restructuring or might not be usable at all.

Use Bob as a documentation assistant, not a replacement for documentation writing. Always review generated content for accuracy, relevance and tone before committing it to your repository. Validating assumptions and adapting outputs to your product and audience help ensure your documentation remains trustworthy and genuine.

Bob works like a collaborative partner in your documentation workflow, helping teams ideate faster by analyzing repositories, surfacing structure and generating actionable starting points. With custom modes, you can tailor Bob’s behavior to match your documentation goals, whether that’s improving onboarding, clarifying project structure or keeping documentation in sync with a growing codebase.

Used thoughtfully, Bob complements the expertise of developers and technical writers to produce reliable AI code documentation. Teams can maintain accuracy and trust while reducing the upkeep of documentation work by combining AI-generated drafts with human review and judgement. The result is clearer, more maintainable documentation that evolves alongside your project.

For more information on how AI can support code documentation, and best practices for using it effectively, see AI for code documentation: Benefits and top tips on IBM Think.