Skip to content

docs: hand the landing-page role from the README to maka.apache.org #4684

Description

@Astro-Han
English

Follows #4307 Q4; supports #3404.

Problem

README.md and README.zh-CN.md run 291 and 287 lines and still serve as landing page, install guide and architecture summary. Since #4660, maka.apache.org is the landing page and the downloads path. The README and the repository description still open with "local-first AI agent workspace" while the homepage uses the positioning settled in #4307.

Outcome

Both READMEs and the .asf.yaml description open with the #4307 sentence, and the README keeps only what a reader inside the repository needs. Everything that describes the product to a newcomer links to the site instead.

Work

  • Replace the opening of both READMEs and the .asf.yaml description with: "Apache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did."
  • Point the badge row and "Quick start" downloads at https://maka.apache.org/en/downloads/; drop the recommendation to build from source as the only path, and keep the Desktop Nightly and npm snapshot labels consistent with the downloads page.
  • Cut "Why Maka", "Surfaces" and "Current capabilities" to a paragraph each that links the site; keep "Architecture", "Repository layout", "Local data and recovery" and "Development and verification" as the repository-facing content.
  • Keep the two READMEs section-for-section identical, as today.
  • Site test or docs check that the three surfaces carry the same sentence, so they cannot drift again.

Out of scope: homepage copy, which lives in website/src/copy/ and changes through #3404's fact-check cadence.

简体中文

承接 #4307 Q4;支撑 #3404

问题

README.mdREADME.zh-CN.md 分别 291、287 行,仍同时充当 landing page、安装指南和架构摘要。自 #4660 起,maka.apache.org 已是 landing page 和下载入口。README 与仓库描述仍以 "local-first AI agent workspace" 开头,而首页用的是 #4307 定下的定位句。

目标

两份 README 与 .asf.yaml 的 description 以 #4307 定位句开头,README 只保留仓库内读者需要的内容;面向新人介绍产品的部分一律链接官网。

工作项

  • 两份 README 开头与 .asf.yamldescription 改为:"Apache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did."
  • 徽章行与 "Quick start" 的下载指向 https://maka.apache.org/en/downloads/;不再把源码构建作为唯一推荐路径,Desktop Nightly 与 npm snapshot 的标注与下载页保持一致。
  • "Why Maka"、"Surfaces"、"Current capabilities" 各缩为一段并链接官网;"Architecture"、"Repository layout"、"Local data and recovery"、"Development and verification" 作为面向仓库的内容保留。
  • 两份 README 继续逐章节对齐。
  • 增加站点测试或文档检查,确保三处使用同一句话,不再漂移。

不在范围内:首页文案,位于 website/src/copy/,按 #3404 的事实核查节奏更新。


Drafted with help from Claude Code. I reviewed the final text and take responsibility for posting it.

Activity

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

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions