Skip to content

Docs: infrastructure and structure for documentation overhaul - #1452

Merged
ennru merged 9 commits into
akka:mainfrom
TylerJewell:docs/infrastructure-and-structure
Mar 26, 2026
Merged

ennru merged 9 commits into
akka:mainfrom
TylerJewell:docs/infrastructure-and-structure

Conversation

@TylerJewell

Copy link
Copy Markdown
Contributor

Summary

  • External link registry — New external-links.adoc partial with all external URLs as Antora attributes. One file to update when URLs change.
  • Why Akka — New top-level landing page framing the three barriers (Production Gap, Liability, Specialist Trap) and three dimensions (Reliability, Risk Control, Repeatability).
  • What is Akka — New platform overview page covering full-stack positioning, differentiators, and application types.
  • Who uses Akka — New persona-based navigation page routing Builders, Operators, and Governance teams to the docs they care about, with customer stories by industry vertical.
  • Resources — New top-level section aggregating all external technical content: foundational works (Jonas Bonér's book, Reactive Manifesto, Reactive Principles), product pages, blogs, demos, talks, webinars, customer stories, benchmarks, training, and community.
  • Governance & the runtime — New Understanding page explaining why bolt-on governance fails for agentic AI and how Akka embeds governance in the runtime for EU AI Act compliance.
  • Homepage + navigation restructure — Updated homepage with positioning-led content, SDD-first tutorial ordering. Nav reordered: Why Akka (with What is Akka and Who uses Akka nested) → Tutorials → Understanding → Developing → Operating → Resources → Reference.
  • Docs overhaul specification — Full spec added at docs/docs-overhaul-spec.md covering positioning, writing standards, platform details, page audit, and implementation requirements.

Each change is an individually reviewable commit.

Test plan

  • make local or Docker-based Antora build succeeds with no new errors
  • All new pages render correctly (why-akka, what-is-akka, who-uses-akka, resources, governance-and-the-runtime)
  • Left nav shows correct hierarchy and ordering
  • External links in Resources page resolve
  • Homepage reflects new positioning and SDD-first tutorial order
  • No title case in page headings (except proper nouns)
  • No competitor mentions in customer-facing pages

🤖 Generated with Claude Code

TylerJewell and others added 8 commits March 25, 2026 09:58
Create external-links.adoc with all external URLs as Antora attributes
(akka.io product pages, blog posts, customer stories, demos, webinars,
foundational resources, community links). Include it in the global
partials chain so every page can reference external links via attributes.

When a URL changes, update it in one place — every page picks it up.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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>
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>
Lists every user persona (Builders, Operators, Governance & Oversight)
with curated links to the docs they care about. Includes customer
stories organized by industry vertical. Serves as a routing page for
both humans and AI agents.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Browsable collection of all non-docs content organized by type:
foundational works (Reactive Manifesto, Reactive Principles),
product pages, application types, blogs, demos, talks, webinars,
customer stories, benchmarks, training, and community links.
All URLs use the external link registry.

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>
CLAUDE.md provides context for any Claude session working on this
codebase: positioning, documentation principles, platform details,
PR strategy, build commands, and repo structure.

docs/docs-overhaul-spec.md is the full specification for the
documentation restructuring project including writing standards,
page audit, use case mappings, integration details, llms.txt
spec, and implementation requirements.

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

Copy link
Copy Markdown

Hi @TylerJewell,

Thank you for your contribution! We really value the time you've taken to put this together.

Before we proceed with reviewing this pull request, please sign the Akka Contributors License Agreement:

https://www.lightbend.com/contribute/cla

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>
@TylerJewell
TylerJewell force-pushed the docs/infrastructure-and-structure branch from 791660d to 36dec4c Compare March 25, 2026 22:11

@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.

I agree, this adds necessary background that wasn't covered before.

The spec should not be added, I think. But we can merge and remove it later.

3. Editing individual `nav.adoc` files for section-level changes

### External Link Registry
All external URLs defined as Antora attributes in a **single central file**: `docs/src/modules/ROOT/partials/external-links.adoc` (new file). Included by every page via the existing `include::ROOT:partial$include.adoc[]` chain.

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 only makes it harder for humans to look at content sources. No gain AFAICS.

Comment on lines +322 to +326
Follows the **llms.txt specification** created by Jeremy Howard (fast.ai/Answer.AI, Sep 2024). Both files are **fully auto-generated** every time the Antora docs are built. No hand-maintained files. The existing `docs/src/modules/ROOT/pages/llms.txt` (currently hand-maintained) is replaced by generated output. The build pipeline (`docs-prod.yml`) handles rsyncing to `doc.akka.io`.

**Standard file names and purposes:**

- **`/llms.txt`** — A curated **index** in Markdown format. Contains a project summary, organized H2 sections of links (`- [Title](url): description`), and an `## Optional` section for supplementary content that can be dropped when context is tight. An agent reads this to understand what docs are available, then selectively fetches only the pages it needs. Small file (1-5 KB).

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.

"No hand-maintained" and "curated" is a contradiction, isn't it?

[discrete]
== xref:ROOT:why-akka.adoc[Why Akka]

Three barriers stand between AI prototypes and production: the **Production Gap**, **Liability**, and the **Specialist Trap**. xref:ROOT:why-akka.adoc[Learn how Akka solves them].

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.

I can imagine better formatting as a list.

Akka is the agentic systems platform built for Reliability, Risk Control, and Repeatability at enterprise scale. The only full-stack platform for agentic AI: developer experience, runtime, and governance in one integrated system.

[discrete]
== xref:ROOT:why-akka.adoc[Why Akka]

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.

Title links are generally hard to discover by the reader. But we have those already.

@@ -0,0 +1,57 @@
= Governance & the runtime

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.

I find the & strange.

@ennru
ennru merged commit d36a988 into akka:main Mar 26, 2026
10 checks passed
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.

3 participants