# Doc linking in NEWS

**URL:** <https://discourse.julialang.org/t/doc-linking-in-news/39520>\
**Category:** Internals & Design\
**Tags:** question\
**Created:** [May 15, 2020, 12:43pm UTC](https://discourse.julialang.org/t/doc-linking-in-news/39520 "2020-05-15T12:43:38Z")\
**Posts on this page:** 5\
**Page:** 1

<div class="post-metadata">

**Author:** ![jne](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jne/32/6341_2.png) [@jne](https://discourse.julialang.org/u/jne)\
**Post date:** [May 15, 2020, 12:43pm UTC](https://discourse.julialang.org/t/doc-linking-in-news/39520/1 "2020-05-15T12:43:38Z")

</div>

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](https://github.com/JuliaLang/julia/pull/34149))

why not link [`@timed`](https://docs.julialang.org/en/v1.5-dev/base/base/#Base.@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](https://docs.julialang.org/en/v1.5-dev/manual/functions/#Keyword-Arguments-1) for examples and context… without having to find it.)

---

<div class="post-metadata">

**Author:** ![StefanKarpinski](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/stefankarpinski/32/24_2.png) [@StefanKarpinski](https://discourse.julialang.org/u/StefanKarpinski)\
**Post date:** [May 15, 2020, 1:39pm UTC](https://discourse.julialang.org/t/doc-linking-in-news/39520/2 "2020-05-15T13:39:05Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![jne](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jne/32/6341_2.png) [@jne](https://discourse.julialang.org/u/jne)\
**Post date:** [May 15, 2020, 1:51pm UTC](https://discourse.julialang.org/t/doc-linking-in-news/39520/3 "2020-05-15T13:51:20Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![fredrikekre](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/fredrikekre/32/1688_2.png) [@fredrikekre](https://discourse.julialang.org/u/fredrikekre)\
**Post date:** [May 15, 2020, 1:59pm UTC](https://discourse.julialang.org/t/doc-linking-in-news/39520/4 "2020-05-15T13:59:48Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![non-Jedi](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/non-jedi/32/3645_2.png) [@non-Jedi](https://discourse.julialang.org/u/non-Jedi)\
**Post date:** [May 15, 2020, 3:39pm UTC](https://discourse.julialang.org/t/doc-linking-in-news/39520/5 "2020-05-15T15:39:57Z")

</div>

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.