“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 (2)
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! 😅).It's becoming a Markdown hell devs now spend more time analyzing the .md files.