Skip to content

docs: improve IA for AI agent builders — add developer quick start#14

Open
ekline[bot] wants to merge 1 commit into
mainfrom
docs/persona-ia-review-2026-03-30
Open

docs: improve IA for AI agent builders — add developer quick start#14
ekline[bot] wants to merge 1 commit into
mainfrom
docs/persona-ia-review-2026-03-30

Conversation

@ekline

@ekline ekline Bot commented Mar 30, 2026

Copy link
Copy Markdown
Contributor

Summary

A persona-based information architecture review identified that the AI Agent Builder persona — Fastn's primary target audience — has no code-first entry point in the documentation. The entire Python SDK, CLI, and MCP programmatic setup are undocumented in docs/. This PR adds a Developer Quick Start page and places it as the first item under "Getting started" in the navigation.

Persona context

AI Agent Builder — An intermediate-to-senior developer integrating Fastn's SDK or MCP server into an AI agent to give it access to 250+ enterprise tools. Their goal is to install the SDK, configure auth, and make their first tool call as fast as possible.

Top 3 findings from IA review

Rank Priority Persona Issue Affected area Proposed fix
1 High AI Agent Builder No SDK/CLI/MCP developer documentation exists — the primary persona has no code-first entry point Entire docs site — missing section Create a "Developer quick start" page with SDK install, auth setup, and first tool call; add to top-level nav
2 High Automation Builder Quick Start Guide buried below reference content in Flows nav; "Your First Automation" links to UCL tutorials instead of Flows Quick Start SUMMARY.md, your-first-automation.md Reorder Flows nav to put Quick Start first; add Flows Quick Start link to "Your First Automation"
3 Medium All personas Only 10% of pages have internal cross-links — personas can't navigate between related concepts without sidebar All 88 pages Add contextual cross-links to key pages (triggers→scheduling, connectors→auth, UCL→SDK)

What this PR fixes

Finding #1: Creates getting-started/developer-quick-start.md covering:

  • pip install fastn-ai and configuration (env vars + CLI login)
  • First tool call via dynamic proxy (fastn.slack.send_message)
  • Semantic tool discovery with get_tools_for()
  • Full agentic workflow examples (OpenAI + Anthropic Claude)
  • Multi-tenant support with tenant_id
  • Troubleshooting table for common errors
  • Cross-links to UCL embedding, MCP server, Flows, and multitenancy docs

Also updates SUMMARY.md to place "Developer Quick Start" as the first item under "Getting started", giving the AI Agent Builder persona immediate visibility.

Remaining items (follow-up work)

How to verify

  1. From the perspective of an AI agent builder visiting the docs for the first time:
    • Open the sidebar → "Developer Quick Start" should be the first item under "Getting started"
    • The page should take them from pip install to a working LLM tool-calling loop in 6 steps
  2. Verify all internal links in the new page resolve (4 cross-references to existing pages)
  3. Verify code examples match the SDK source (fastn-sdk/python/fastn/client.py)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

0 participants