How Someone Who Quit Documentation Three Times Started Maintaining It With a Single /docs-init Skill
Complex structure kills documentation — the survivors were just two files: index.md and log.md
“I always start organizing and then give up.”
That’s what I said the day I first brought up the myWiki idea. I’d built project spaces in Notion, carefully written READMEs, set up Obsidian vaults. Done all of it, abandoned all of it. They all had one thing in common — I’d be full of energy when setting things up, and then nobody would maintain them. More precisely, I wouldn’t.
Why Complex Documentation Dies
I used to believe that a well-organized structure created a well-organized project. product/, architecture/, policy/, guide/, reference/, roadmap/ — just the names make it feel systematic. But do you know what happens after about two months? It’s all either empty or stale.
There’s a reason for it. When you make an important decision in the middle of coding and start wondering “which folder does this go in?” — that’s already too much friction. On top of that, when you’re running two or three projects, you end up with over 200 .md files, and that’s not organization — it’s just moved the fragmentation to a different location. Everything scattered across chat is now scattered across folders instead.
There’s a clear tipping point where managing documentation becomes heavier than the actual work. Once you cross that line, nobody does it.
What the Survivors Have in Common
So I took an honest look at things. Which files actually survived to the end across my projects. The result was pretty clear. Two files: index.md and log.md.
Why those two — there’s a practical reason. When you open a project at any random time, you need to know “where is this project right now?” within a minute, and index.md with the current state all in one place did that. log.md stacks up as append-only with ## [YYYY-MM-DD] feat | one line, and because it’s not heavy, I kept writing in it.
One principle came out of that. “If staying current is heavy, nobody will do it.” One-line append-only is the sustainable minimum unit. The decision was simple — fix the entry points, and create type folders when content actually exists.
The /docs-init Skill: Hardcoding This Lesson
But as my projects multiplied, doing this judgment manually every time got tedious. Starting a new project and spending time thinking “what folders does this project need?” felt wasteful, and mistakes crept in too.
So I turned it into a Claude Code skill. When you run /docs-init, Claude reads that project and creates only what’s needed. Two core principles.
First, the entry trio (index/todo/log) are fixed as single files. If they get scattered, nothing stays current. These three files get created for every project, always.
Second, no empty folders. Only folders with actual content get created.
What this looks like in practice — I ran /docs-init once on the Hansaiam online art museum project, and only two of the six type folders were created: architecture/ and guide/. The product/ folder wasn’t created, because there were no requirements documents. “Create only what exists” in visible form.
You don’t have to manually design the structure every time. When experience crystallizes into a skill, the next project gets the same judgment. This is part of what it means to use Claude Code properly.
Documentation Is Preparation for the Next Session
A well-made index.md is all you need to restore context within a minute when you open a project you haven’t touched in a while. After experiencing this, my perspective shifted.
log.md isn’t for preventing yourself from forgetting what you did. It’s a handoff note for the next Claude Code session. LLM meets you for the first time every new session. When a new session opens and reads log.md, it immediately knows how far things have come. It’s also a way to solve the agent context interruption problem through documentation.
When you redefine documentation from “something you organize later” to “something you bundle in the same commit as the work,” the burden disappears. Changed some code? Add one line to log.md, update one line of status in index.md — if you just do these two things, your project documentation stays alive.
Try running /docs-init on one of your current projects, or if you don’t have one, just create a single docs/index.md file. Start by writing one paragraph on “what state is this project in right now?” That’s where the first page of documentation that doesn’t go stale begins.