Separating how-to guides ('gathering info' sections) from reference documents

[sei-renae]

• resolves references/decision_points contains a mixture of 'references' and 'how-to-guides' per diataxis.fr #723
• resolves Inconsistent formatting of Gathering Info... sections of Decision Point reference pages #537

[ahouseholder]

Please consider which/whether this PR is intended to address:

• Recast "Gathering information about..." sections into a data mapping discussion #362
• Suggested defaults should appear on relevant decision point pages where applicable #522
• Inconsistent formatting of Gathering Info... sections of Decision Point reference pages #537
• references/decision_points contains a mixture of 'references' and 'how-to-guides' per diataxis.fr #723

If it is, update the resolution keywords in the description accordingly.

[j---]

moving the "gathering information" sections to the how to instead of reference like this makes sense to me.

[ahouseholder]

I like the split of Gathering Info off into the HowTo section of the docs. That part is fine.

1. What I'm left with though is that in docs/reference/decision_points/* there are (at least as of the current commit) no breadcrumbs pointing from the reference doc to the corresponding howto doc.

I suggest leaving something akin to the following behind in each of the relevant reference pages.

!!! tip Gathering Information about Foo

      See this [HowTo](link) for advice on gathering information about the Foo decision point.

Adjust wording to taste, I'm mostly concerned that (a) there is a link to it, and (b) it's probably in a call-out.

2. In the new "HowTo" pages, I think it would make sense to also include the current version example block somewhere near the top of the page.

python exec="true" idprefix=""
from ssvc.decision_points.ssvc.automatable import LATEST
from ssvc.doc_helpers import example_block

print(example_block(LATEST))

Other than that I can't think of anything else at the moment.

[ahouseholder]

I had previously commented:

Please consider which/whether this PR is intended to address:

• Recast "Gathering information about..." sections into a data mapping discussion #362
• Suggested defaults should appear on relevant decision point pages where applicable #522
• Inconsistent formatting of Gathering Info... sections of Decision Point reference pages #537
• references/decision_points contains a mixture of 'references' and 'how-to-guides' per diataxis.fr #723

If it is, update the resolution keywords in the description accordingly.

After conversations with @sei-renae, I believe this PR, once complete, would resolve #723 and #537, while leaving #522 and #362 as future work. I added closing keywords to the PR description consistent with this observation.

[ahouseholder]

I made a few fixes directly before doing this review. There are still a few changes I'd like to see before we finish this per comments that follow.

[sei-vsarvepalli]

All markdown changes checkout fine.

[ahouseholder]

A couple previous comments remain unresolved, and I had a couple new ones on this revision. In particular, the sentence fragment in Human Impact is a blocker for merging.

[sei-renae]

@ahouseholder I think I got it all this time