Steel Docs Diátaxis framework audit

steel-docs-diataxis-audit.md

Steel Docs Diátaxis Audit

Audited August 3, 2026 against 185 MDX pages in steel-dev/docs.

Summary

Overall: about 6/10 adherence. The docs contain all four Diátaxis modes, and several pages execute them well, but the modes are not consistently separated or clearly signposted. The strongest areas are how-to and reference; explanation and beginner tutorials are underdeveloped.

Diátaxis does not require four literal top-level folders, but it does require each document to have a clear job and avoid muddling modes. Product-oriented hierarchies are acceptable when user needs still drive the content. See the official guidance on complex hierarchies.

Mode	Score	Assessment
Tutorials	5/10	Good examples exist, but there is no coherent learning path.
How-to guides	8/10	Strong integration guides, recipes, and deployment material.
Reference	8/10	API/SDK coverage is strong; some handwritten pages mix in guidance.
Explanation	4/10	Present mostly as sections inside other pages rather than dedicated conceptual material.
Mode separation	5/10	Many pages try to teach, direct work, explain concepts, and provide reference simultaneously.

What is working

The Playwright pair is close to ideal Diátaxis:

• The integration guide is concise and task-oriented: requirements, connection instructions, and a working result. That is a solid how-to guide.
• The Cookbook recipe provides a controlled runnable experience, expected output, and safe variations. That is tutorial-like.
• They link to each other instead of duplicating the same purpose.

The Agent Traces API page is also good reference material: endpoint, response schema, field definitions, query parameters, and errors. It largely follows the product rather than a user workflow, which is exactly what reference should do. See the official Diátaxis reference guidance.

There is substantial practical coverage:

• 48 Cookbook recipes
• 27 integration pages
• self-hosting and feature-specific operational guides
• generated API and SDK reference

This gives the docs a strong “help me accomplish something” layer.

Where it breaks down

The largest issue is mixed-purpose pages.

Session Lifecycle combines:

• conceptual explanation of session states;
• instructions for reserving IDs and releasing sessions;
• parameter/reference facts;
• billing guidance;
• an SEO-oriented FAQ.

The page is useful, but readers cannot immediately tell whether it is a concept guide, task guide, or reference page.

Mobile Mode similarly contains an overview, a configuration procedure, implementation details, and a substantial “Why This Matters” explanation. Those are three different Diátaxis jobs.

Agent Traces Overview combines capability reference, operating instructions, an API example, use cases, and conceptual explanation.

The navigation reinforces this ambiguity. The primary sidebar is organized around Steel’s product model—Sessions API, Agent Traces, Credentials API, Files API, Stealth—rather than what the reader is currently trying to do or understand. See overview/meta.json. Product organization is not inherently wrong, but individual page intent needs to be clearer inside it.

Tutorials are the main content gap

There is only one explicitly labeled Quickstart: Sessions API Quickstart.

It has a managed beginning and conclusion, but it needs improvement as a tutorial:

• It promises TypeScript and Playwright, then uses Puppeteer for the connection example.
• It does not show the expected result of running the final browser automation.
• The “Session Features” section starts expanding into reference material before the learner has completed a clearly verified outcome.
• The FAQ adds more reference material to the learning flow.

A Diátaxis tutorial should lead a beginner through a controlled, repeatable experience and minimize digressions. See the official tutorial guidance.

Several Cookbook recipes are actually better tutorials than the official Quickstart, but they are presented as an undifferentiated recipe catalog rather than a progressive learning path.

Explanation is comparatively weak

Some explanation exists:

• Intro to Steel
• Steel Local vs Steel Cloud
• “Why This Matters” sections in feature pages

However, most of it is shallow, promotional, or embedded inside task pages. There are few dedicated documents answering questions such as:

• How does a Steel session relate to CDP, contexts, and pages?
• Why choose persistent profiles versus credentials?
• How do timeout and inactivity timeout interact conceptually?
• When should an agent use mobile mode?
• How do proxies, stealth, fingerprints, and CAPTCHA solving relate?
• Steel Cloud versus self-hosting: architectural and operational trade-offs

Those would form a genuine understanding-oriented layer. See the official Diátaxis explanation guidance.

Recommended approach

Do not reorganize all 185 MDX files into four new top-level folders. Instead:

1. Assign every maintained page a primary mode in frontmatter: tutorial, how-to, reference, explanation, or index.
2. Improve the Sessions Quickstart into one verified Playwright learning journey.
3. Treat runnable Cookbook projects as tutorials and concise Integration pages as how-to guides.
4. Split the most heavily mixed pages, starting with Session Lifecycle, Mobile Mode, Authentication, CAPTCHA Solving, and Agent Traces Overview.
5. Add a small Concepts/Understanding group for extracted explanation pages.
6. Keep API and SDK reference pages descriptive; link outward for procedures and rationale.
7. Preserve the recent SEO/AEO material, but keep FAQs subordinate to each page’s primary purpose.

The docs are already useful and technically broad. The main Diátaxis opportunity is not writing substantially more material—it is making each existing page more decisive about the single user need it serves.