Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

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

Open Beginner friendly
  • Is something wrong?
#1,270 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-2 days
Newbie friendliness
70/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
c, markdown
Domain
documentation

Research direction

Start by reading the existing docs/ directory to understand the current flat structure. Identify which files belong to guide, reference, explanation, and internals based on the issue's classification. Create the new subdirectories and move files accordingly, updating links in index.md and other documents. Ensure the docs-claims PATHS class and Pages build pass without broken links. Finally, draft a simple tutorial in docs/guide/ with executable examples.

Written by the indexing model from the issue text.

Description

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.

Dominant language
C
Stars
3
Forks
7
Avg merge
3h 56m
Merged PRs (30d)
102

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from InauguralSystems/EigenScript

All issues in InauguralSystems/EigenScript

Similar issues

More C issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.