How we reorganized app documentation before it became unmaintainable

The problem was not lack of documentation

Daily Sudoku had plenty of documentation. Too much, in fact.

We had a product plan, a Google Play guide, store listing copy, ASO research, a changelog, Play Console checklists, IAP setup notes, performance benchmarks, and release notes. Each file made sense when it was created. The problem appeared later, after the app had gone through internal testing, public launch, follow-up polish, and several rounds of release preparation.

At that point, the docs stopped answering one question at a time.

The plan was no longer just a plan. It had old AAB hashes, validation logs, product system descriptions, Play Console state, future ideas, and finished checklist items. The store listing file still had old inline release notes. The changelog had grown into a long scroll where one day of work could be buried between months of unrelated history. A checklist that said it was not a status log still contained a dated snapshot of Play Console state.

None of this was dramatic. That is why it is dangerous. Documentation decay usually does not look like a broken build. It looks like hesitation: “Where should I put this?” Once that question appears several times in one day, the documentation system is already leaking.

We had just finished a UX hardening pass on the app. That work became a separate post about running a heuristic UX critique on a React Native game. The next problem was less glamorous but just as practical: if we could not write down what changed cleanly, the next release would get slower.

The rule: one document, one job

The reorganization started with a blunt rule: each document should answer one primary question.

Not every question. Not every useful detail. One primary question.

For this app, the main questions were:

• What is currently open and needs action?
• What happened on a specific day?
• What changed in a specific app version?
• What is the stable store listing copy?
• How does the product work today?
• What is the operational gate for Google Play?
• What is the step-by-step runbook for publishing?

Those questions do not belong in the same file.

The mistake we had made was treating “documentation” as a single bucket. Once a project moves from development into store operations, that bucket fills with different kinds of material: live status, historical facts, user-facing release notes, technical references, and procedural runbooks. They age differently. They are read by different future versions of ourselves.

So we split by job, not by topic.

The new structure

After the cleanup, the Sudoku docs looked like this:

docs/app-sudoku/
  README.md
  SUDOKU_PLANO.md
  SUDOKU_HISTORICO.md
  historico/
    SUDOKU_2026_07_16.md
  releases/
    SUDOKU_0_1_0.md
    SUDOKU_0_1_1.md
    SUDOKU_0_1_2.md
  SUDOKU_LOJA_LISTING.md
  SUDOKU_REFERENCIA_PRODUTO.md
  SUDOKU_GATE_GOOGLE_PLAY.md
  SUDOKU_GUIA_GOOGLE_PLAY.md
  SUDOKU_PLAY_CONSOLE_CHECKLIST.md
  aso/
    SUDOKU_ASO_*.md

It is more files than before, but less guessing. The next edit has an obvious home.

Living plan: only what is alive

SUDOKU_PLANO.md is now the living plan. It should not accumulate build hashes, old validation logs, full product reference material, or a detailed history of what happened last month.

Its job is to answer: what is true now, what is still open, and what should happen next?

We kept status, current priorities, open Google Play gate items, roadmap, and risks. We moved stable product descriptions and old gate detail elsewhere.

The practical test is simple: if a completed item no longer changes what we should do next, it probably belongs in history or reference, not the living plan.

History: one file per date

The old changelog was one long Markdown file. It preserved facts, but it was painful to search and edit. We converted it into an index plus daily files:

SUDOKU_HISTORICO.md
historico/SUDOKU_2026_07_16.md

The index contains one line per date. The detailed daily file contains the actual notes.

We intentionally kept the app name in the filename (SUDOKU_2026_07_16.md). A date alone can collide with other apps in file search. The app prefix makes search results useful inside a monorepo.

For days with multiple entries, we do not create multiple files. The file stays one per date, and the suffix becomes an internal heading:

# 2026-07-10

## 0.1.0+9

...

## desenvolvimento 0.1.1

...

This avoids filenames like SUDOKU_2026_07_10_0_1_0_9.md, which are harder to predict and worse for search.

Release notes: one file per app version

Release notes are not the same as history.

History answers: what happened on this date?

Release notes answer: what changed since the previous version?

Those can cross date boundaries. So release notes live under releases/, one file per semantic app version:

releases/SUDOKU_0_1_2.md

We first tried including the Android build number in the filename, like SUDOKU_0_1_2_11.md. That was wrong. Google Play and the App Store can diverge. Android has versionCode; iOS has buildNumber. A rejected or re-uploaded build can change one store without changing the semantic app version.

The filename now represents the app version. Store-specific builds live inside the file:

# 0.1.2

## Builds

| Store       | Build          |
| ----------- | -------------- |
| Google Play | versionCode=11 |
| App Store   | TBD            |

That one choice prevents a future iOS release from breaking the naming scheme.

Store listing: stable copy only

SUDOKU_LOJA_LISTING.md had become a mix of stable store copy and old release notes. We removed the inline notes and left only the listing, store references, and an index to versioned release files.

This matters because Play Console copy and release notes are updated on different rhythms. Listing copy can stay stable for months. Release notes change every upload.

The same separation helped when we worked on the post-launch landing page. That process is described in why we rebuilt the app landing page after the Play Store launch. Store copy, landing page copy, and release notes overlap, but they are not the same artifact.

Product reference: how the app works

SUDOKU_REFERENCIA_PRODUTO.md now holds stable product and system contracts: implemented features, visual direction, scoring rules, Daily Challenge behavior, animation principles, telemetry contracts, ads/privacy behavior, settings, and quality checks.

This is not a backlog. It is not a release plan. It is the answer to: how does the product currently work?

That distinction matters. If a future developer wants to understand why Auto Notes costs credits or how the score formula works, they should not have to dig through release gates or old AAB hashes.

Google Play gate: validation details without polluting the plan

SUDOKU_GATE_GOOGLE_PLAY.md holds the detailed operational gate: Play App Signing hashes, AAB history, validation facts, smoke references, and old Play Console contingencies.

Some of that detail is still useful. None of it belongs in the living plan.

The runbook remains separate in SUDOKU_GUIA_GOOGLE_PLAY.md: that file tells us how to publish. The gate reference tells us what has been validated or needs validation context. The Play Console checklist remains a checklist, not a status diary.

The small but important cleanups

We also removed a scratch file named Pendencias.md. It contained temporary instructions, an old design prompt, manual-test notes, and a grocery list. That file was harmless until it was not. Leaving it in docs/ tells future contributors that scratch belongs in project documentation.

It does not.

We moved ASO research into an aso/ folder with its own README, moved .DS_Store files to the trash, and ran a mechanical Markdown link check after every migration. The final check across the Sudoku docs reported no broken relative links.

The template we will reuse

For the next app, this is the structure we will start with instead of discovering it halfway through release work:

docs/app-name/
  README.md
  APP_PLANO.md
  APP_HISTORICO.md
  historico/
    APP_YYYY_MM_DD.md
  releases/
    APP_X_Y_Z.md
  APP_LOJA_LISTING.md
  APP_REFERENCIA_PRODUTO.md
  APP_GATE_GOOGLE_PLAY.md
  APP_GUIA_GOOGLE_PLAY.md
  APP_PLAY_CONSOLE_CHECKLIST.md
  aso/

Not every app needs every file on day one. But the jobs should be clear from the start.

The lesson

Documentation becomes hard to maintain when documents are named by vibe instead of responsibility.

“Plan” becomes everything not yet categorized. “Changelog” becomes a scroll of every fact. “Listing” becomes release notes plus store copy. “Checklist” becomes a status log. That works until it does not.

The fix is not to write less. The fix is to decide what each file is allowed to contain.

The best documentation structure is the one that makes the next edit boringly obvious.