Ok @svx thank you for clearing this up. Now we all know what is bad, but we still have no solution to the problem.
What about, instead of including things, using simple pages which point some links to the other area, if there is not more info?
I mean the concret problem i found was with templates and views.
I would expect all the needed docs in the developper area in this case.
Even though some of the infos are also interesting for Integrators.
But for Integrators, there could be an intro page with some infos, if needed with links to developer docs, which explain more technical stuff. Sure the speaking in the developer area might be a bit different, but that should be fine, if someone want to dive deeper into a topic. There is no strict line between a being a developer or an integrator. Of couse the best would be to have a special chapter just written for Integrators, in the right language with the right amount of information they need. I'm not holding anyone back, to write more Integrator or user docs. But my focus for now is, to fix the developer story of Plone first. And the most docs we have in these two areas are developer docs, in information and tone. So I would restructure it a bit, to have the developer part complete and fill the gaps in the Integrator part with index pages with a summary, which describes what can be done and points to the dev docs if needed.
Beside that, I thing we should build a Developer Crash Course, like the training but more condenced to a backend developer audience. This way it is easier to get people on board with backend developing. I'm thinking of material which takes not more than 1-2 days to go thru. This training should also have pointers into the dev docs, for details information about the different topics. I would like to have a discussion about, what people thing a backend developer should learn first. But I'll start another topic for that.