3 posts tagged with "Developer Experience"

Docusaurus gives you a reasonably accessible starting point, and most sites then lose some of it. The losses rarely come from the framework itself. They come from custom colors, custom components, a sticky banner someone added for a launch, and years of Markdown written without anyone checking alt text or heading order. This post lists the WCAG 2.2 AA issues we look for first on a Docusaurus site, where each one usually comes from, and how to test for them.

Docs as code is a shipping model, not a shopping list. Copying another company's toolchain gives you their cost structure without their constraints, and most of the cost lands on the person maintaining the pipeline rather than the person writing the page. This is which parts pay for themselves, what has to be true before each one does, and what is theater.

Good writing helps a reader who is already on the right page. Good structure gets them there, tells them within seconds whether they are in the right place, and lets them find the one step they need without reading the rest. When we review a help center that customers say is "hard to use", the prose is rarely the problem. The problem is that every page has a different shape, so readers cannot predict where anything will be.