Hacktoberfest 2026：维护者为十月标记出来的 issue，仍然开放、适合新手。 浏览 Hacktoberfest issue

docs: organize docs/ by audience (guide / reference / explanation / internals) and add a real tutorial

未关闭 适合新手
  • 哪里不对？
#1,270 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
2/5
预计耗时
1-2 天
新手友好度
70/100
Issue 类型
文档
描述清晰度
描述清楚
活跃度
活跃
技术栈
c, markdown
领域
documentation

调研方向

首先阅读现有的 docs/ 目录以了解当前的扁平结构。根据 issue 的分类，识别哪些文件属于指南、参考、解释和内部实现。创建新的子目录并相应地移动文件，更新 index.md 和其他文档中的链接。确保 docs-claims PATHS 类和 Pages 构建通过且没有损坏的链接。最后，在 docs/guide/ 中起草一个包含可执行示例的简单教程。

由索引模型根据 Issue 内容生成。

描述

area:docs help wanted kind:decision

Problem. docs/ is 30 files in one flat directory, with no signal of audience.

  • Reference: SPEC, GRAMMAR, BUILTINS, STDLIB.
  • Explanation: OBSERVER, ARCHITECTURE, TRACE.
  • Internal engineering notes: JIT_STAGE5_INLINE_IC, TEST_COVERAGE_ANALYSIS, GAP_ANALYSIS, EMBED_OBSERVER_VALIDATION.
  • CI operations: CI.md.

index.md exists, but a newcomer cannot tell where to start, and there is no tutorial.

What mature languages do. Split by what the reader is doing: the Diátaxis quadrants of tutorial, how-to, reference and explanation. Python ships Tutorial / Library Reference / Language Reference / HOWTOs / What's New. Rust ships The Book / std docs / the Reference / Rust by Example / the Nomicon.

Bar.

  1. docs/guide/ holds a real tutorial whose every example runs under the executed-fence gate: install, first program, the observer in one page, a small real program.
  2. docs/reference/, docs/explanation/ and docs/internals/ (or move internals to hq) hold the existing files by audience. Every moved file is reachable from docs/index.md, which states the four sections and whom each serves.
  3. No broken links: the docs-claims PATHS class and the Pages build pass. Front doors (README, llms.txt) point at the guide first.
  4. A gate or the doc-enrolment population ensures that a new doc lands in one of the sections, not the root.

Ranked #3 of the docs follow-ups (2026-09-22 comparison with other languages). Mostly file moves, but many links.

Done when

  • Decision recorded in a comment here: split docs/ by audience (docs/guide/ tutorial + docs/reference/ + docs/explanation/ + docs/internals/, or internals moved to hq) or keep docs/ flat with docs/index.md as the only map. Also: whether internal engineering notes (JIT_STAGE5_INLINE_IC, TEST_COVERAGE_ANALYSIS, GAP_ANALYSIS, EMBED_OBSERVER_VALIDATION) stay public. Name the chosen option and why.
  • If adopted: docs/guide/ holds a tutorial (install, first program, the observer in one page, one small real program) whose every example runs under the executed-fence gate.
  • If adopted: every existing docs/*.md lives in exactly one section directory; docs/index.md names the four sections and whom each serves and links every moved file; README.md and llms.txt link the guide first.
  • If adopted: tools/docs_claims_check.sh (PATHS class) and the Pages build pass with zero broken links, and a gate refuses a new .md at the docs/ root (planted once).
  • If rejected: close with the reason.
主要语言
C
星标
3
派生
7
平均合并
11 小时 30 分钟
30 天内合并 PR
271

环境准备

在 Codespaces 中打开

在浏览器里用你自己的 GitHub 账号启动这个项目的开发容器。

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

InauguralSystems/EigenScript 的其他 Issue

查看 InauguralSystems/EigenScript 的全部 Issue

相似的 Issue

更多 C Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。