Hey everyone! I've been working on a math learning website as a side project for the last 18 months, and it's grown quite a bit. I have a solid understanding of the code and project structure, but I'm realizing that I need to start documenting things for when it gets more complex. I'm not looking for the usual advice like "write more comments" but rather how to keep track of project-specific quirks and important information without cluttering the source code. I've heard about having a wiki on GitHub, but mine is private, so I'm unsure about that. I'd love to hear your suggestions for how you document your own projects or what companies do for similar issues. Thanks!
5 Answers
For long-running projects, I've found that creating a simple `/docs` folder in the repo works wonders. Just markdown files to jot down all those quirky behaviors, like "this behaves like X due to Y." It stays private if your repo is private, offers easy linking between notes, and keeps comments out of your code. Future you will thank you for having everything right next to the code!
A great approach is to write notes like you're onboarding a future teammate. Just quick pages on specific topics—like quirks in routing or database issues. It forces clarity, and it’s a nice way to stay organized! I've definitely thanked my past self a few times for it.
Start with a solid `README.md`, which is pretty standard. If your documentation needs grow, then consider using the GitHub wiki for more elaborate documentation, but best to have more than just 10 lines to avoid clutter. It's all about striking the right balance!
Consider using architectural diagrams and models too! Diagrams, interaction models, and even some process models can be really helpful. They’re great for people working in software architecture and can make complex ideas more digestible. Learning about TOGAF frameworks might also boost your documentation game.
For a solo project, just a private wiki is usually enough. GitHub wiki works fine for private repos, or you could try Notion or Obsidian for something that's a bit more versatile. Just find what fits your style!
Yeah, it's a bummer about the payment, but if you can swing it, it could be worth it!
I didn’t realize GitHub has private wikis too! Great to know that’s an option, although it seems like it's a paid feature.