Skip to content

Docs: high-priority page rewrites for positioning alignment - #1453

Merged
ennru merged 49 commits into
akka:mainfrom
TylerJewell:docs/high-priority-rewrites
Mar 26, 2026
Merged

ennru merged 49 commits into
akka:mainfrom
TylerJewell:docs/high-priority-rewrites

Conversation

@TylerJewell

Copy link
Copy Markdown
Contributor

Summary

Depends on #1452 (infrastructure and structure PR).

10 high-priority page rewrites to align with revised positioning (Reliability, Risk Control, Repeatability), SDD-first approach, and writing standards:

  • Spec-Driven Development — Canonical SDD page with AI Marketplace as primary install path, CLI as fallback in admonition
  • AI Agents concepts — Three barriers/dimensions framing, foundational AI positioning
  • Agents SDK — Overview with when-to-use guidance, renamed "Skeleton" to "Basic Agent Structure"
  • First tutorial — SDD presented as recommended path, manual walkthrough as secondary
  • Development process — SDD leads the page, manual workflow in callout box
  • Architecture — Full-stack platform framing (Reliability/Risk Control/Repeatability)
  • Guardrails — Risk Control showcase with EU AI Act connection
  • Data sanitization — Governance-built-in positioning with right-to-explain
  • AAO — Service tiers and reliability guarantees
  • Glossary — 19 new terms (A2A, ACP, Agentic AI, EU AI Act, Guardrails, LLM, MCP, SDD, etc.)

All pages: second-person voice, page metadata attributes, See Also sections with external links, all existing code examples preserved.

Test plan

  • Antora build succeeds with no new errors
  • All rewritten pages render correctly
  • Code examples still display (include directives intact)
  • External links in See Also sections resolve
  • No title case in headings
  • No "we" in voice — second-person throughout

🤖 Generated with Claude Code

@github-actions github-actions Bot added the documentation documentation related label Mar 25, 2026
@TylerJewell
TylerJewell force-pushed the docs/high-priority-rewrites branch 2 times, most recently from 392b930 to a79e1ef Compare March 25, 2026 22:12
TylerJewell and others added 26 commits March 26, 2026 21:55
New top-level entry point framing the three barriers (Production Gap,
Liability, Specialist Trap) and three dimensions (Reliability, Risk
Control, Repeatability). Includes competitive comparison table and
links to external content via the link registry.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

# Conflicts:
#	docs/src/modules/ROOT/pages/why-akka.adoc
Brief platform intro covering full-stack positioning, key
differentiators, service tiers (Fast Prod through Sovereign Cloud),
and application types with links to akka.io product pages.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
New Understanding page explaining why bolt-on governance fails for
agentic AI (immutable records, human intervention, authorization
capture, PII scrubbing) and how Akka embeds governance in the runtime.
Covers EU AI Act alignment and compliance certifications.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Update antora.yml nav order: ROOT (Why/What/Who) -> Tutorials ->
  Understanding -> Developing -> Operating -> Resources -> Reference
- ROOT nav.adoc now includes Why Akka, What is Akka, Who Uses Akka
- New resources-nav.adoc for the Resources top-level section
- Rewrite homepage: lead with positioning (three barriers/dimensions),
  SDD-first tutorial ordering, Governance & Runtime in Understanding,
  AAO leading Operating, Resources section added

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add: Anthropic, biopharma, decisioning, Doctolib, explainability,
Hanafee, infosec, Llaama, Manulife, QCon, regionalized,
reputational, Swiggy, Telecom, Tubi to the Vale spelling
accept list. These are proper nouns, industry terms, and customer
names used in new documentation pages.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Update antora.yml nav order: ROOT (Why/What/Who) -> Tutorials ->
  Understanding -> Developing -> Operating -> Resources -> Reference
- ROOT nav.adoc now includes Why Akka, What is Akka, Who Uses Akka
- New resources-nav.adoc for the Resources top-level section
- Rewrite homepage: lead with positioning (three barriers/dimensions),
  SDD-first tutorial ordering, Governance & Runtime in Understanding,
  AAO leading Operating, Resources section added

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Rename H1 from "Project structure" to "Architecture". Add page
metadata attributes. Add Overview section connecting to the three
dimensions (Reliability via runtime, Risk Control via governance,
Repeatability via developer experience). Fix voice to second-person.
Add See Also with external links. All existing technical content
preserved.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add page metadata with governance personas. Add Overview connecting
guardrails to runtime-embedded governance and EU AI Act compliance.
Fix voice to second-person. Reorganize under clearer subsections.
Add See Also with governance and trustworthy AI links. All existing
code examples preserved.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Rename H1 to "Data Sanitization". Add page metadata with governance
personas. Frame PII scrubbing as runtime-level governance property
with EU AI Act right-to-explanation connection. Fix voice to
second-person. Add See Also section. All code examples preserved.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add page metadata. Add Overview framing SDD as primary approach.
Lead with 6-step SDD lifecycle connected to Repeatability dimension.
Move manual development workflow into TIP.manual admonition callout.
Fix voice to second-person. Add See Also with SDD links. All
existing component descriptions and technical content preserved.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add page metadata for operator personas. Add Overview section.
Add service tiers (Fast Prod, Day 2 Ops, Business Continuity,
Sovereign Cloud). Add Reliability section with availability
guarantees. Fix voice to second-person. Add See Also with demo
links. All existing operational content preserved.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add page metadata. Add 19 new entries: A2A, ACP, Agentic AI, AI
Agent, Constitution, EU AI Act, Guardrails, LLM, MCP, Production
Gap, Reliability, Repeatability, Risk Control, Sanitizer, SDD,
Specialist Trap, Spec-Driven Development, Three Barriers, Three
Dimensions. All 25 original entries preserved. New entries include
cross-references linking related terms.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Rename H1 to "Agents". Add page metadata with component-type.
Add Overview with when-to-use, when-not-to-use, and component
relationships. Rename "Skeleton" to "Basic Agent Structure".
Fix voice to second-person throughout. Add See Also with
AI concepts, guardrails, memory, and protocol links. All
code examples and include directives preserved.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Rename H1 to "AI Agents". Add page metadata. Add Overview with
component relationships. Add three barriers section (Production
Gap, Liability, Specialist Trap) and three dimensions section
(Reliability, Risk Control, Repeatability). Fix voice to
second-person. Add See Also with external links. All existing
content preserved including video embed.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add page metadata. Flip the TIP to present SDD as the recommended
approach, with the manual Java walkthrough as secondary for
understanding components under the hood. Add See Also with SDD,
planner tutorial, and Akkademy links. All existing tutorial
content, code examples, and images preserved.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add page metadata. Add Overview with when-to-use guidance. Lead
installation with AI Marketplace plugin as primary path, CLI
fallback in TIP.manual admonition. Fix voice to second-person
throughout. Add See Also with external links. All existing
technical content preserved (maturity levels, specify/clarify/
plan/tasks/implement/build workflow, command table).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Lowercase non-proper-noun words in page title and all xref labels
across sanitization page, governance page, and who-uses-akka page.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace separate Package and Deploy sections with a single section
describing two paths: direct deployment to Akka via CLI/Console,
or GitOps via CI/CD pipelines. Add CI/CD integration link.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Lowercase H1 and xref label in concepts index page.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Akka component names (Endpoints, Agent, Consumer, etc.) are proper
nouns and should be capitalized.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Service tiers are sales content and do not belong in SDK docs.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Remove entries that are sales/positioning only: EU AI Act, Production
Gap, Specialist Trap, Risk Control, Three Barriers, Three Dimensions.
Fix capitalization: "Component ID" (not "id"), "Workflow step" (not
"Step"). Update cross-references in remaining entries that pointed
to removed entries.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
These are positioning/sales content. The AI Agents concepts page
should focus on technical concepts: tokens, prompts, memory,
orchestration, evaluation. Updated page-summary accordingly.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Remove the platform graphic, "Developers create..." paragraph, and
product table from the tutorial introduction. These belong in
conceptual/overview pages, not a hands-on tutorial.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Rewrite Getting Started section with three-tier installation:
1. Primary: AI Marketplace plugin (4 steps with commands)
2. Alternative: Clone plugin from Akka repository
3. Fallback: akka specify init <dir> (in TIP.manual admonition)

When plugin is installed, /akka-specify:setup handles environment
setup (CLI, Java, Maven, Akka download token). Updated "Using Akka
specify" section to clarify it describes fallback behavior.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace Java/Maven-first approach with three-step quickstart:
install Akka plugin from marketplace, run /akka-specify:setup,
run first specification. CLI fallback in admonition. Hands-on
Java tutorials moved to secondary section. Component names
capitalized throughout.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
TylerJewell and others added 22 commits March 26, 2026 21:57
Three-tier installation: marketplace (primary), clone from
https://github.com/akka/ai-marketplace (alternative), CLI
akka specify init (last resort). Clone instructions show how
to add the cloned directory as a local marketplace in Claude Code.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Consolidate marketplace add, plugin install, and reload into one
code block. Clone-from-repo is now a TIP inline rather than a
separate section. Two clean steps: install plugin, run setup.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Remove starthere.adoc as separate nav entry — it was a duplicate
of index.adoc with outdated prerequisites content. Replace with
redirect to index.adoc. Nav now has single "Tutorials" entry
pointing to index.adoc. Spec-first agent listed before hello world.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The Getting Started / Tutorials page now appears in two places in
the nav: as a top-level "Getting started" entry after Why Akka,
and as "Tutorials" in its own section with sub-pages.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Include explicit git clone instructions for ai-marketplace repo
as alternative to marketplace add. Reword CLI fallback as "No
plugin capability for your AI assist?" pointing to SDD page.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
You are already on this page — no reminder needed.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Plugin name changed: akka-specify@ai-marketplace -> akka@ai-marketplace
Skill prefix changed: /akka-specify: -> /akka:
Updated in Getting Started, SDD page, and spec-first tutorial.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace claim of immediate running service with accurate description
of what happens: Akka builds a specification and guides you through
plan, implementation, build, and test steps.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Consolidate all fallback/alternative install guidance together
in Step 1 before moving on to Step 2.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Move spec-first greeting Agent into its own section with description
of SDD command workflow. Hands-on tutorials now contain only the
manual Java tutorials.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add width=100% to Spec-driven and Build your first Agent tables
so they match the width of multi-row tables below.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Remove the platform graphic, descriptive paragraphs, and product
table from the tutorial introduction. Same cleanup as the hello
world tutorial — these belong in conceptual pages, not tutorials.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Prerequisites now list only AI coding assistant and OpenAI key.
Java, Maven, curl, Git, and Akka CLI moved to "Additional
prerequisites for those without an AI marketplace" subsection
since the plugin installs these automatically.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The plugin is the primary path, not optional.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace Unicode box-drawing character tables in code blocks with
proper AsciiDoc tables for consistent HTML rendering. Affects
plan output, task summary, implementation summary, and build
results sections.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Remove "Without the plugin" title from TIP admonition. Remove
Akka Code Init Demo from See Also — not relevant to SDD.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace <<_package_service>> and <<_deploy>> with
<<_package_and_deploy>> to match the merged section.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@ennru
ennru force-pushed the docs/high-priority-rewrites branch from a79e1ef to 31e0bd2 Compare March 26, 2026 20:58

@ennru ennru left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good improvements in this PR.
LGTM.

Comment on lines -19 to -22
include::ROOT:partial$local-dev-prerequisites.adoc[]
* Git
* An AI coding assistant like Claude Code to build and implement the specification
* xref:quick-install-cli.adoc[Akka CLI] (_installed automatically if you use the Akka Claude Code plugin_)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IIUC the Claude plugin does NOT install Java and Maven

If you were able to create and build an empty project, then you're all set and you can continue on to the tutorials.


This page has moved. See xref:getting-started:index.adoc[Tutorials].

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can add a renamed tag to that page.


This configures your environment — ensuring the Akka CLI is installed, Java and Maven are available, and your Akka download token is properly configured. Once setup completes, you are ready to start building.

NOTE: Not using Claude Code? Akka supports 30 different AI assist tools. Visit https://doc.akka.io[doc.akka.io] for installation instructions for your tool.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This link to doc.akka.io doesn't make sense.

@ennru
ennru merged commit 4198193 into akka:main Mar 26, 2026
10 checks passed
This was referenced Mar 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation documentation related

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants