coder / coder/balatrobot

docs(phase-3): write how-to guides (install, launch, instances, write-a-bot, contribute)

Open
#228 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
72
Forks
18
PR merge metrics
No merged PRs in 30d

Description

Part of #224 — v2 docs rewrite (Diátaxis).

## Goal

5 goal-oriented guides: `install.md`, `launch.md`, `instances.md`, `write-a-bot.md` (incl. first-bot walkthrough + screenshots), `contribute.md`.

## Tasks

- [ ] Execute every guide top-to-bottom on a real machine (macOS; Docker via balatrobox) before finalizing
- [ ] Move examples/troubleshooting out of reference pages into the guides that own them
- [ ] Port contributing.md into how-to/contribute.md (verify Makefile targets + workflows)
- [ ] Open write-a-bot.md with a "first bot" walkthrough (from example-bot.md: health → gamestate → start → play → loop) and have a newcomer follow it — fix every friction point
- [ ] Apply the style guide: first-mention links (term → page map), plain-language glosses

## Dependencies

- Blocked by: #226 (Phase 1 — reference), #227 (Phase 2 — explanation)
- Blocks: Phase 4 (automation), Phase 5 (ship)

## Done when

- [ ] All 5 guides executed end-to-end on a real machine
- [ ] Newcomer completed the walkthrough without help

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the dependency issues #226 and #227, then inspect example-bot.md, contributing.md, the existing reference pages, the Makefile, and workflows. Execute each guide on macOS with Docker via balatrobox, and have a newcomer follow the first-bot walkthrough. Done means all five guides work end-to-end and the walkthrough can be completed without help.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, python
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.