“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?
Top comments (8)
I think it is a good pattern to hold dev docs as markdown files in a repo and to publish consumer docs (if it’s a library or such) as a separate website, that clearly decouples things and provides comprehensive go-to routes for a project user. Also, talking about routing 😅 extracting deeper docs into dedicated files (inside
/docsfolder or alike) and referencing them in the main README is the best way for larger internal docsets — otherwise the README becomes barely consumable/readable. IMO, it should just give a quick overview (and abuse<details>tag! 😅).Honestly, this makes a lot of sense.
I’m starting to realize the README probably works better as a quick entry point, while deeper docs live separately.
Also good point about the /docs structure — I may move more things there over time.
Maintaining documentation synchronization is a notorious pain point. Treating documentation as code by leveraging single-source-of-truth strategies—like pulling from centralized markdown files or using automated tools—is vital to preventing the inevitable drift that leads to technical debt.
That's why bigger companies hire Technical Writers – that's a whole separate profession of people whose job is to take care of documentation 😉
I'd advise keeping the internal docs in the repo + adding a link to the user-facing docs. In this case, in README, you'll have a short overview of the project + how to run it locally + links to internal dev docs and to external user-facing docs. This way, you will avoid duplicating content. which leads to maintenance hell.
That’s actually very strong advice, thank you.
I really appreciate it. 🙏
I’ll try to organize my project documentation more that way over time. But first I need to organize everything in my head 😀
Good luck! :)
It's becoming a Markdown hell devs now spend more time analyzing the .md files.
Yeah, it really starts feeling that way sometimes 😄
At some point you realize you’re maintaining documentation almost as much as the actual project.