Normally I don’t bother with documentation because it’s normally just me working on games, or because the person I’m working with doesn’t need all the details of how the game is going to work, just enough to do their part (e.g. the artist only needs to know what to draw), or because I’ve already got a game functional before I ask for any additional help (e.g. I give translators advanced copies of the game so they can see the context and confirm the translation is suitable).
However, when I did my 2.0 revamp of Minesweeper, I did actually do some designing before I started and I made use of GitHub’s project feature to keep track of what I had to do.
I only just realised I forgot to add some of my design work to the repo so I’ll add it later when I’ve improved the quality enough to make the handwriting legible.
When I do make design documentation, I always do it on paper first and go digital afterwards.
And when I do design stuff it doesn’t always have a 1:1 correlation with the code because it’s more abstract than the code itself.
With a lot of games the best documentation you can hope for is git history, and perhaps GitHub issues and PRs.
Some people don’t bother trying to make their git history neat and tidy because it’s extra effort, but I tend to try to spend the time to keep my history well organised and include brief descriptions about what the changes do or why they’re needed.
For Minesweeper 2.0, the commit history is the closest thing to documentation.
You can also look at the issues and PRs.
I don’t know if you can see the milestones, but I used a milestone too.
And I don’t know if you can see projects, but I used a project.
If you can’t see those, here’s an annotated screenshot of the project, part way through development:
It’s a kind of kanban board.
Notably, you can see some ‘stretch goals’ that didn’t make it to the final version.
When you learn how to use them, GitHub’s projects can be incredibly useful for keeping track of things.
It didn’t stop me keeping a todo list on paper as well, but it helped when I accidentally lost the bit of paper
When I worked on Dark & Under we didn’t really document things, we discussed ideas and our decisions were documented by our conversations, and we can’t make those public unless redact all the personal information and opinions that were discussed, and that would take some serious effort.