Skip to content

docs: PR1 — Foundation & framing (About Akka, SEO, standards) - #1702

Merged
ennru merged 9 commits into
akka:mainfrom
TylerJewell:docs/pr1-foundation
Jul 10, 2026
Merged

ennru merged 9 commits into
akka:mainfrom
TylerJewell:docs/pr1-foundation

Conversation

@TylerJewell

@TylerJewell TylerJewell commented Jul 8, 2026 •

Copy link
Copy Markdown
Contributor

PR1 — Foundation & framing

  • Rename Why Akka → About Akka; new What is Akka? landing aligned to canonical positioning (llms-full.txt).
  • Seven About Akka capability pages (What is Akka?, Agents incl. AutonomousAgent, Orchestration, Memory, Streaming, Automated Operations, Akka Internals) with diagrams.
  • SDK/Libraries SEO disambiguation: JSON-LD in head-meta, header switcher notice; Libraries nav/link retargeted to the libraries guide.
  • Spec-driven development page: docs-voice pass (marketing words removed) + workflow SVG.
  • Writing standards + Vale rules (marketing-words, Akka Specify Plugin terminology).

No dependencies. PR2 and PR3 build on these pages.

🤖 Generated with Claude Code

About Akka section (rename Why Akka -> About Akka, What is Akka landing,
seven capability pages with diagrams, Akka Internals), SDK/Libraries SEO
disambiguation (head-meta JSON-LD + header switcher), spec-driven page
voice pass + workflow SVG, writing standards and Vale rules.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@github-actions github-actions Bot added the documentation documentation related label Jul 8, 2026
TylerJewell and others added 5 commits July 9, 2026 05:26
…switcher

Rewrite the Akka Internals opening to the canonical enterprise definition
and the four-layer platform framing (Components/Runtime/Cloud Stack/
Harnesses) with the platform-intro graphic, matching What is Akka. Simplify
the SDK/Libraries switcher: SDK 'for building agentic AI systems',
Libraries 'an actor framework'.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Replace bursty, cutover, masterless, replayable, repoint, rollout,
runbook, swappable, browsable, toolchain, and buildable with common-
dictionary equivalents so the Vale.Spelling CI gate passes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The Akka.MarketingWords rule introduced in this PR runs repo-wide, so it
flags two pre-existing 'seamlessly' uses (specify/deploy, sdk/metric).
Reword them so the repo is clean under the new error-level rule.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- ACP folded into A2A (drop standalone bullet; A2A note).
- Soften agent-exposure wording (you add endpoints; not automatic).
- Link capability claims to detail: compaction -> agents/memory#_compaction.
- Note Views as a query path for the latest value in Akka Memory.
- Disambiguate SDK Akka Streaming from the Akka Streams library, with links to each.
- Link the Akka Specify Plugin mention to its install step.
- Add structural AI-tell guidance to writing-standards.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Reduce machine-generated cadence across the seven capability pages: convert
em-dash appositives to colons or short sentences, break stacked triads, vary
sentence length, and trim adjective pile-ups. Voice only — canonical
definition, the developer-experience/runtime/governance tagline, the
four-layer framing, and all claims are unchanged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@TylerJewell
TylerJewell marked this pull request as ready for review July 9, 2026 19:37
@TylerJewell TylerJewell changed the title [DO NOT MERGE] docs: PR1 — Foundation & framing (About Akka, SEO, standards) docs: PR1 — Foundation & framing (About Akka, SEO, standards) Jul 9, 2026
ennru and others added 3 commits July 10, 2026 13:51
Replace the small low-contrast disambiguation sentence with a single
legible inline switch in the topbar: "You're reading the SDK docs ·
Switch to Libraries". Larger (.82rem) and higher-contrast text, with an
underlined switch link that brightens on hover. Still injected into
#topbar-nav and hidden below 1024px, as before.

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

@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 updated the new images to have black background so they work even for the light theme.
LGTM.

@@ -1 +1 @@
* xref:index.adoc[Akka Libraries]
* https://doc.akka.io/libraries/akka-core/current/typed/guide/index.html[Akka Libraries, window="new"]

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'll work on building a more proper libraries landing page in Akka Dependencies basically copying what we right now have in https://doc.akka.io/libraries/index.html

Somewhere here https://doc.akka.io/libraries/akka-dependencies/current/

@ennru
ennru merged commit b4eaccd into akka:main Jul 10, 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.

2 participants