I'm linking DM-37544 and DM-33034 to this as I think they need to be part of the plan for how we do this:

• The first is a technote that Nate Lust and I are planning to write, and one of the things we've discussed including is a section in pipeline YAML files where the major output dataset types can be defined, with documentation, with those definitions checked against the tasks in the pipeline. I think that's the source of this information.

• The second is a long-stalled ticket that involves having scons (in drp_pipe, in this case, as a prototype) that generates content to be included in the Sphinx docs from the pipelines in a package. That is very much alive in my mind as the way to get the doc source into a more public, presentable location. When I'm not putting out fires, I am actively working on blockers for that ticket.

Why can't we use the `doc` fields of the Connections definitions for that documentation, instead of (separately?) putting it in the pipeline yaml?

I'd like to reserve those doc fields for "this is how this dataset is used by this task", though that may be more relevant for inputs than outputs. I wouldn't be opposed to the output connection docs the default documentation for dataset types that aren't documented in the pipeline file.

Partly, my question is because we already have those fields and wouldn't have to implement too much extra (I hope? Jonathan Sick?) to insert them into the already existing Task Topic Type for PipelineTasks.

Why would you expect that the documentation fields you want to add to the yaml pipeline files would be different from the docs that we can already put on Output Connections?

On many tasks, there probably wouldn't be a difference. But in some cases the description of the dataset type depends on configuration and sometimes its context in the pipeline ("this is the final photometric calibration, produced by combining the outputs of FGCM with ..."). I also want to use the pipeline definitions to help distinguish between public, science-user-visible dataset types and those that should be considered pipeline implementation details. Put another way, the documentation on the connection is a generic description of what the dataset type might be given some configuration, and the documentation in the pipeline would be the description of a particular realization of that.