Documenting dev policy: github issue linking

[john-science]

What is the change?

1. The primary purpose of this PR is to explicitly document the fact that ARMI does not link to issues or PRs in code (think docstrings).
2. While at it, I also found some spelling and grammar errors in the Developer Manual, and fixed those.
   a. Sorry, I can't help myself.
3. Also, I removed a link to a 4-year-old ticket from another repo that was clearly abandoned ages ago.

Why is the change being made?

To close #1864

---

Checklist

• This PR has only one purpose or idea.
• Tests have been added/updated to verify any new/changed code.

• The code style follows good practices.
• The commit message(s) follow good practices.

• The release notes have been updated if necessary.
• The documentation is still up-to-date in the doc folder.
• The dependencies are still up-to-date in pyproject.toml.

[drewj-tp]

At the risk of bike shedding, I'd be curious to hear from other developers too.

[drewj-tp]

I've found external links to be helpful as supplemental resources. An empty link is not helpful, yes. But it can provide people references to go digging later if they want. Or for more context behind the change.

In the case of the material theoretical density changes that kicked off this work, there is a lot of good discussion in #1440. And that context and discussion motivates some strange fixes that a future developer may have questions about. Putting some explanation in comments or docstrings could be sufficient, but is that "documenting well?"

Alternatively, I can do a git blame and find the commit that introduced a change with interesting commentary. And then find the PR that contains that commit, find the issue that PR closes, and then I have some more context and background on a change.

There's some motivation to make everything self sufficient (e.g., "without recourse to the originator") that I get.

Is there a balance that can be struck? Linked issues can be stale or wrong and that's less helpful. But they can be quick ways to provide useful background. Maybe

Do not add bare links to external tickets or change requests in code.
    A link to a GitHub issue on its own is not helpful. Provide enough information via comments or
    docstrings that a passing developer does not need to search for more. Links should be used as
    supplemental resources only, with the bulk of the context being added in the source code.

?

[john-science]

I mean, my notion goes like this:

1. We have managed for a decade without doing this yet.
2. I have seen projects that do this, and inevitably, their docstrings and internal docs suffer hard.
3. I personally, me, don't want to have to go do homework when I'm reading the code. It takes what should be reading a one-sentence docstring to reading a 4-page story.
4. I don't think "background" and "history" help people understand code. If you can't say "This works like this, because of this" then just giving an infinite amount of context and history and background is just telling people you can't document the feature clearly, and are giving up.

BUT I will admit there is a lot of personal bias above, so let me think about this some more.

[john-science]

Also, it occurs to me that GitHub is the third git platform/tool this project has been on.

Pointing to a GitHub ticket isn't particularly useful if we've moved on to GitLab or whatever the new hotness is in 6 years.

[drewj-tp]

All great points. I don't have any good rebuttals. And we should definitely encourage any documentation to stand on its own

[drewj-tp]

Thanks @john-science!