In this direction, if the "basic" tutorial is sourced from the "full" tutorial, a comment on the
documentation should be put ("This is sourced as a basic tutorial, this section should give
an overview of the feature and be self-contained.") and then, rewrite the following to glue it.
The full tutorial should be:
- Overview
- Details
- Caveats
and the basic tutorial should be:
- Source from Overview
- Note: "If you find this feature useful for your case, continue reading here where you will find
a more detailed discussion and the caveats to consider."
Something like this is what came to your mind?
Seems like an all-or-nothing proposal that is quite different from what is done today and doesn't contribute significant added value.
The interplay between the tutorial and the authoritative reference sections are substantially correct today. I'd advise making any changes try and fit within the current setup rather than trying to redesign the entire thing.
