DynamoDB Cheat Sheet

Context

Amazon DynamoDB’s documentation served two audiences with very different needs: decision makers and developers.

The decision making group tended to be less technical. It consisted mainly of owners, project managers, and stakeholders. They made almost all of the actual purchasing decisions, and would come to the DynamoDB docs site in order to asses the service. Their needs were geared more towards high-level overview content.

The developer group would mainly come to the DynamoDB docs site after their institution had adopted DynamoDB. They tended to need information that was much deeper in the weeds. Setup requirements, API reference, and troubleshooting detail.

The docs handled this with a conventional split: overview pages at the top, and deeper reference guides underneath.

Problem

The user feedback on several overview pages ran strongly negative. From looking at the support tickets, I could see many experienced engineers were not finding the details they needed. Many of these support tickets had been closed as “user error” because the information was available somewhere. It was just not available where they were looking.

Adding developer detail to the overview pages could have helped fix developer’s problems, at the expense of making it more difficult for decision makers to evaluate and buy DynamoDB.

Constraints

Any solution had to better surface needed information for developers, without making evaluation more difficult and murky for non-developers.

Approach

I treated the constraints as the design spec rather than obstacles. Each one pointed to a structural decision:

• Don’t alienate either audience → a new, separate page that developers would recognize as theirs and non-developers would feel free to skip. Naming did the work: calling it a cheat sheet told both audiences exactly what it was in two words.
• Surface buried information without duplicating reference docs → keep it entirely separate from both the overview tier and the reference tier, with its own clean URL, and link it prominently from the DynamoDB landing page as an explicit decision point: “evaluating?” or “building?”
• Head off trouble before it becomes a ticket → limit the content to what developers searched for most when first standing up a DynamoDB instance: the high-level requirements and the key gotchas. [Based on search-log analysis of the top N queries / on the highest-volume support categories.] Nothing else.

The result was a single, bookmarkable, shareable page that a new engineer told “go set up DynamoDB” would see immediately and could work from directly.

Result

The cheat sheet rapidly became one of the most-visited pages on the DynamoDB documentation site. Within 3 months it ranked #3 by overall traffic. The page itself started with and maintained avery positive Negative Participation Profile (NPP), while NPP on the affected overview pages and overall docs site fell by 4%. The overview pages stayed clean for the evaluating audience, and the reference docs remained the single source of truth for detail.

Live page: docs.aws.amazon.com/amazondynamodb/latest/developerguide/CheatSheet.html

What stayed

The cheat sheet is still published and maintained. I’ve also carried forward a general principle in my further work: using constraints as a way to drive a new solution.