If you’ve spent any time in software development, you understand the importance of documentation. But for many tech professionals, writing and editing documentation is a time-consuming pain—and a task they could accelerate through judicious use of AI. But how can you most effectively use AI to complete documentation?

Before we plunge into that, it’s important to differentiate some broad types of documentation, including:

• Process documentation (breaking down how you did something)
• Product documentation (here’s how it works; breaks down into system and user documentation, targeted at different audiences)
• Requirements documentation (where’s what we need!)
• Planning documentation (here’s how we’ll build it!)

There are further breakdowns, of course, including:

• Technical specifications
• Product roadmaps
• Troubleshooting/QA guides
• Tutorials
• Standards documentation
• Metrics documentation
• System/sysdmin documentation

It’s a lot, in other words, especially when you consider how each of these documentation types subdivide further into discrete components; for example, planning documentation requires a description of the initial request or problem, development steps, an explicit breakdown of who’s managing the project, and so on.

Despite that complexity, though, documentation also shares some common principles:

• Target Audience: Understand who you're writing for. Is it a non-technical manager, a marketing team member, or an internal support agent? Tailor the language and level of detail accordingly.
• Clarity and Concision: No matter what type of documentation you’re writing, avoid jargon and overly technical language. Explain things in simple terms, using visuals like screenshots or diagrams if needed.
• Structure and Organization: Break down complex features into bite-sized steps. Use headings, bulleted lists, and a logical flow to make information easy to find and follow.
• Actionable Steps: When it comes to process and planning documentation, focus on "how-to" instructions, providing clear steps users can follow to complete a task.
• Examples and Use Cases: For tutorials and guides, include real-world examples and scenarios to illustrate how users can benefit from the new features.

Harnessing Generative AI for Faster Documentation:

Applying a generative AI chatbot to your documentation requires some thought:

• Start with a clear and concise prompt that outlines the target audience, purpose of the document, and key features; and the more detailed, the better.
• Have the AI adopt a persona: tell the AI something like, “You are a project manager who wants to create process documentation around mobile app creation…” and then flow from there. For some reason, most generative AI chatbots tend to work better when you start the prompt with a persona.
• Don't expect perfection—or correct facts. The AI-generated draft will need editing and revision for clarity and accuracy. While it’s nice to have something quickly generate a lot of text, it doesn’t have your expertise. To that end…
• Use the draft as a starting point, filling in the gaps with specific details and technical information.
• Once you have the initial draft, collaborate with the AI tool to expand explanations and include relevant examples.

When it’s time for your second draft:

• Ask the AI to rephrase complex sections in simpler terms or rewrite sentences for better clarity.
• Prompt the AI to generate code snippets or embed screenshots to illustrate specific steps. Double-check those code snippets, as AI can get those disastrously wrong on occasional.
• Use the AI to suggest real-world use cases and scenarios to make the information relatable to the users.

Don't be afraid to experiment with different prompts and refine your approach. In the end, you’ll need to apply a heavy hand to the AI’s output in order to ensure accuracy, tailor information to your specific project, and give your audience what it needs.

The Benefits of AI-Assisted Documentation

Given how much human oversight you’ll need to apply to any attempt to have a chatbot write your documentation, why do it?

• It Saves Time: Offloading the initial draft generation frees up your valuable time for bug fixing, feature development, and other critical tasks.
• It Can Improve Clarity: Generative AI can help bridge the communication gap, ensuring your technical knowledge is translated into user-friendly language.
• Maintain Consistency: The AI can help maintain a consistent voice and style across your documentation, ensuring a smooth user experience.
• Boost Collaboration: Sharing AI-generated drafts can kickstart internal discussions and ensure everyone is on the same page about the update.

For those reasons alone, you might consider careful use of generative AI in the course of documenting your projects. At the very least, you can use the time saved by working with AI and apply it to things that interest you, like coding new features or coming up with new products.