I am honestly and with all respect disagreeing
There are lots of reasons:
- ripping things out of context
- assuming knowledge of people and what they did/read
- style, length, readability and visual appearance
- missing content
- broken links
- breaking releases
I could continue here with a lot of more reasons
Thing is, people (developer, no offense ! ) thing quite often, ‘just’ use a include and we’ re done …
Most of the time a link to the document or part of the document would be way better. Because you do not take stuff out of context, etc, etc
I took almost 3 full work days to fix that on all the training docs and we’ re still not 100% done !
People (user, reader) got confused there, docs were broken, etc because of reasons mentioned above.
I see the same by lots of projects who including their README as index.html in their Sphinx based docs.
This is wrong !
There are fundamental differences between a README and a index/intro/teaser/about of your project.