uttrflow / uttrflow/uttrflow-swift

Docs/README.md does not list soak.md or ui-tests.md, and no document links to either

Open Beginner friendly
#653 0 comments 0 reactions 0 assignees View on GitHub
area:general documentation good first issue P2
Dominant language
Swift
Stars
4
Forks
17
Avg merge
3h 32m
Merged PRs (30d)
277

Description

## What happens

`Docs/README.md` indexes 88 of the 90 files in `Docs/`. The two it leaves out, `Docs/soak.md` (how to run `make soak`) and `Docs/ui-tests.md` (how to run `make uitest`), are not linked from any other Markdown file in the repository (`git grep -l 'soak.md\|ui-tests.md' -- '*.md'` finds nothing), so the only way to find them is to list the directory.

`Scripts/docs_audit.sh` checks that links resolve, but not that every document is reachable from the index.

## Why it matters

`make soak` and `make uitest` are in `make help`, and these are the pages that explain what they need (hours of running, a windowing session) before somebody starts one.

## Acceptance criteria

- Both documents are listed in `Docs/README.md` under a fitting heading.
- `Scripts/docs_audit.sh` gains a check that every `Docs/*.md` other than `Docs/README.md` is linked from `Docs/README.md`, and fails naming the file when one is not.
- `make docs-audit` passes; say in the pull request that removing one of the new index lines makes it fail.

## Where to start

- `Docs/README.md`, `Scripts/docs_audit.sh` section 3 (relative links), which already parses links.
- Read [CONTRIBUTING.md](https://github.com/uttrflow/uttrflow-swift/blob/main/CONTRIBUTING.md) first, and say on this issue that you are taking it.
- Before pushing, run `make verify` (with `DEVELOPER_DIR` pointing at Xcode 26.6 or later). It is the same command CI runs.

**Size:** S, about 1 hour.

Contributor guide

Open the contributing guide

Research direction

Read CONTRIBUTING.md first, then inspect Docs/README.md and section 3 of Scripts/docs_audit.sh, which already parses relative links. Add the two document links and the missing index-coverage check, then run make docs-audit and make verify; done means both files are indexed and removing an index line makes the audit fail naming that file.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown, shell
Domain
build-system, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
88/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.