“At some point, documentation starts feeling like a second project.”
Yesterday I spent time updating my project website and reorganizing parts of the documentation.
Right now I am trying to keep the main README.md clean and focused while moving more detailed information to the project website.
But honestly, the more the project grows, the harder this becomes.
After every new feature or improvement, it starts feeling like I need to update:
- the main README
- additional README file for the NuGet package
- the website documentation
- the live demo project
And keeping all of that updated and aligned over time is becoming harder.
I also noticed that very large READMEs become difficult to maintain and difficult to read. They turn into huge walls of text that overwhelm new contributors and users.
So lately I have been thinking that maybe the README should only:
- explain the project quickly
- show minimal setup
- provide simple examples
- link to detailed documentation externally
And maybe everything else belongs on the website instead.
Still trying to figure out the best long-term approach honestly.
This is the current README structure I am experimenting with:
https://github.com/DebugProbe/DebugProbe.AspNetCore/blob/main/README.md
How do you organize documentation in your projects without constantly duplicating information everywhere?
