Doc linking in NEWS

Internals & Design
1

Hmm, question… When a PR adds to NEWS.md, why is it not practice for the author to link not only the github PR/Issue but also documentation entries?

For example in the 1.5 Release Notes, in

  • The @timed macro now returns a NamedTuple (#34149)

why not link @timed?

(You know, for the casual reader to click into for basic info, perhaps just to peek at what the heck this macro does anyway, or to behold the new documentation with new behavior described, or just to see an example…)

(Seemingly also relevant would be when a section of the manual proper can be linked, for example in the 1.5 Release Notes item on the new implicit kwarg names thing: a reader might enjoy referring to the manual section for examples and context… without having to find it.)

1 Like
2

It would be great if someone wanted to fix up the NEWS entries with links to the relevant docs. This is mostly not there because it’s a fair bit of work to add.

2 Likes
3

I see. I was thinking if it becomes the new practice, PR by PR, responsible by the PR author. As the new 1.6 NEWS is approximately blank.

This would require a change in code reviewers’ expectations.

4

I think that in the HTML docs it would just work if you add the proper Documenter @refs.

5

In general there’s a tradeoff: the more requirements you make of people who write cool new features, the less cool new features you’ll get. To me, making something like this mandatory seems very much on the wrong side of that tradeoff.

1 Like