Yes, you can close the PR. (As far as I am concerned.)

Can we also close down this GitHub PR? I'm unclear whether you need that for ongoing discussion.

Self-merged.

The discussion happening on this ticket can be continued on Community if needed.

Out of curiosity, how did the PR come to your attention, John Swinbank?

I keep an eye on GitHub – that's part of the T/CAM job description.

For an LTD document the best way to do this probably would be to copy/paste in the permalinks to section headers provided by the HTML renderer

When referring to code on GitHub from a JIRA ticket, I tend to create a link to a specific line of code in a specific commit (i.e. https://github.com/lsst-dm/dmtn-020/blob/813237e30a130aa117d958170118eab8e1cf8b98/conf.py#L28, not https://github.com/lsst-dm/dmtn-020/blob/master/conf.py#L28). That's certainly clunky.

That said, while dealing with a moderately large number of comments on DMTN-020 (see e.g. DM-6447), I'd characterize this as gentle friction rather than a serious problem. Of course, it might be more of an issue for those less familiar with our JIRA/GitHub, particularly if they are coming from outside the project.

What would be really nice is if somehow one could hack Github to allow inline commenting on existing code as easily as on a PR or other commit. Then it might be natural to use that UI for the purposes of, say, creating a Github issue.

As it is, without some sort of inline commenting, the barrier to people submitting small corrections/suggestions is much higher. If I have a number of comments on a document, and I want to do it in JIRA or in a Github issue, I have to write my comments in such a way that the references back to the document are at least unambiguous, even if they aren't actually useful in taking the reader straight to the code to be edited. For an LTD document the best way to do this probably would be to copy/paste in the permalinks to section headers provided by the HTML renderer (hover over a section title to see the permalink icon appear next to it).

But this is an order of magnitude more trouble than the use of a natural inline commenting scheme.

Of course, if the commenter is confident enough to actually edit the document, then a PR is the natural vehicle in any event - but even in that case it would be nice to ease the process of also generating a matching JIRA ticket to support the ticket-based workflow of merging the edits to master.

(And if you are now wondering why I didn't just actually edit "enhancement" to "improvement" myself, the answer is that Jonathan Sick and I were deliberately using this as a test case for how to accept comments.)

The use of a PR without an associated ticket (and ticket branch) was an experiment that Jonathan Sick and I devised, trying to find the minimal-effort way for someone to post a comment on an LTD-based document. (In a mild irony, this arose in a discussion of our communication tools, including Confluence, and although we are in total agreement that Github/LTD is the way to go for software documentation, I was gazing with envy on the ease of making inline comments in Confluence.)

The idea was that one could use Github's in-browser code editor and ::note directives to provide a way to place comments inline with document content (as is trivial in Confluence) while staying within the LTD workflow. The least-cost path here is to just click on the edit-pencil icon for the offending file to create the change and associated PR. That flow offers the option of entering a branch name. It would be possible to then go off, create the JIRA issue, then paste "branch/DM-nnnn" into the appropriate field, and create the PR, but that's a bit awkward and manual, and has a race condition where the issue appears before its associated content. Jonathan Sick is going to think about whether this could be more automated somehow. In the mean time, we thought we'd try just accepting the default branch name Github supplies.

Out of curiosity, how did the PR come to your attention, John Swinbank?