AWS Insights

AWS Documentation update — progress, challenges, and what’s next for 2025

Person in cafe viewing AWS docs website on a laptop

Documentation is critically important for our customers, and we’ve been hard at work making significant improvements to the structure, clarity, and discoverability of AWS Documentation. I want to share some of the key progress we’ve made and discuss where we’re heading next with our documentation strategy, including how we’re leveraging AI.

Our global team of technical writers creates and maintains hundreds of thousands of pages of technical documentation for 200+ AWS services. We also have dedicated product, engineering, content strategy, and program teams that build tools, automations, and maintain the Documentation websites. The entire team has been focused on continuous improvements to the AWS Documentation experience. Based on feedback data (thumbs-up, thumbs-down, surveys, and more), we’re making good progress, but we know there’s still a long way to go. Making docs better is one thing, but making AWS docs the best in the industry is the real objective that we’re aiming for.

Optimizing AWS docs for readability and more

Over the past year, we’ve undertaken a comprehensive refactoring of most of the AWS user and developer guides. This wasn’t just surface-level cleanup – we improved consistency and structure and we optimized the content for better readability. We also recognize that many developers are learning AWS from AI tools, so we structured the content to be more effectively consumed by language models, ensuring AI-powered tools (not just Amazon Q, but all public large language models (LLMs) can provide accurate information about AWS topics.

We doubled the number of code samples across our documentation to expand coverage to more AWS services. Developers frequently tell us, “Don’t make me read – just show me some code,” so we know we need many more samples to adequately cover more services. Well-written, idiomatic, and tested code samples are critical to both humans and language models.

We also improved content accessibility. From improving alt-text on images to improving header hierarchy, we’ve made some big strides, and we will continue to invest in making AWS docs accessible by all.

New AWS Decision Guides help you make the right choices

One of the biggest challenges when using AWS is choosing the right service for specific needs. For example, having multiple services that can run containers is great, but having a lot of options can also be overwhelming and confusing. While you could read the documentation for each service to understand their differences and optimal use cases, that’s not a practical way to narrow down the choices. To address this, we created a series of “decision guides” that focus on specific service categories (for example, databases, containers, compute, AI, and others). These guides succinctly outline the differences between services within the categories, and explain what each is optimized for. The positive response to these new guides has encouraged us to expand this approach further and to better integrate this type of content throughout the documentation.

Screenshot showing the decision guides directory

Website improvements make finding content easier

In addition to the content improvements, we’ve been busy improving the structure, navigation, and overall usability of the main documentation website. This started with improving the documentation website’s home page by bringing common destinations front and center (and in my opinion we made it look a little nicer, especially in dark mode!)

Screenshot of AWS Documentation home page

Then we added improved navigation throughout the site, including links to related resources (such as API reference, AWS command line interface (AWS CLI), and SDK), and recommended tasks. We added global navigation controls along the top to access popular destinations in just a few steps — when you visit the docs website, you shouldn’t have to go searching for obvious things like developer tools and code samples. We also made significant improvements to on-site search by adding search auto-suggest and improved search results ranking with concise summaries. Since most developers use Google and other public search engines to find AWS documentation, we’ve also invested in optimizing our content structure and metadata for search engine optimization (SEO) and better external search results.

Screenshot of AWS Documentation search results and auto-suggest

We heard feedback that while the various navigation features are useful, they can also be distracting when trying to read a long guide. So, we added a “focus mode” feature that removes page navigation elements, leaving most of the page real estate to the guide’s content. Data shows that this is a popular feature (and more popular than we expected).

Screenshot of AWS Documentation guide illustrating how focus mode works

Evolving how we use AI to help create AWS Documentation

The recent advances in AI, especially generative AI, offer us new ways to produce documentation. Creating new documentation using AI for new AWS features or services is challenging because LLMs may not have been trained on the new concepts. Our writers need to provide the initial content building blocks (“content primitives.”) To do this, our team of writers produce clear, accurate documentation for these new features to ensure the AI tools can understand and provide thorough and reliable responses. We’ve recently found that by providing engineering design docs and API specifications as part of the prompt (in-context learning), we can leverage LLMs to create some first draft content — even for novel concepts — which accelerates the overall documentation creation process.

We’ve also learned that AI excels at creating what I call “derivative content” — new content that is derived from existing AWS content. For example, if you ask any modern LLM to create a step-by-step guide for deploying a static website on AWS, you’ll usually get a decent response because there’s an abundance of published content on the topic. However, the resulting content might be inaccurate or not represent current best practices. We’ve found that we can create a virtuous cycle by using AI to create the first draft, then having a human-in-the-loop to test, correct, and publish the improved content, ultimately enhancing the language models’ knowledge of the topic. The Decision Guides are a great example of this process. Most of the guides began with AI-generated first drafts through some clever prompting, but then we thoroughly tested and revised the content to meet our documentation standards before publishing.

Our customers expect official AWS Documentation to be the “source of truth,” and we take that responsibility very seriously. We’re finding that AI-generated content is usually a good start (and getting better every day), but nearly always requires some edits to make it 100% technically accurate before we publish it. This is the virtuous cycle in action. And when we show AI-generated content that has not gone through this rigorous check, it will always be clearly labeled as such.

AI also offers promising approaches for content localization and using AI agents to identify outdated or conflicting content. We’re actively building new platforms and tools to harness these AI capabilities and deliver an improved documentation experience. We’re also constantly reminding ourselves that today’s AI capabilities represent the baseline and the technology will only improve from here, so we need to anticipate what will be available in the near future. Generative AI has brought new excitement and energy to my job and many others.

While we’ve made substantial improvements, we know we need to improve continuously. Our goal isn’t just making documentation better — it’s to make documentation as helpful and frictionless as possible, and we have an ambitious roadmap to get us there. More website features, as well as further improvements and additions to the content, are coming soon. I’ll also share some details in the future on how we’re further using AI throughout the documentation lifecycle.

Your feedback wanted!

Are we working on the right priorities? How could we make AWS Documentation better for you? Use the comments below or DM me on LinkedIn or Bluesky.

Greg

Greg Wilson

Greg Wilson

Greg leads the AWS Documentation, SDK, and CLI teams. With a background in software engineering, cloud architecture, and developer relations, Greg has focused on developer efficiency and productivity throughout the majority of his career. In his current role, he leverages his experience to help make AWS more accessible and usable for customers.