search

go-kit / log

A minimal and extensible structured logger
MIT License
185 stars 18 forks source link

Documentation link broken #6

Closed ShayNehmad-RecoLabs closed 1 year ago

ShayNehmad-RecoLabs commented 3 years ago

https://www.thoughtworks.com/radar/techniques/structured-logging in the README is no longer maintained:

image

We should either use a web archive link or link to a different article.

telemachus commented 1 year ago

tl;dr — I'm happy to make a pull request swapping the current link for a Wayback Machine link, but I'm not sure that it's necessary. See below for details.

The link isn't really broken, but it is definitely confusing. Like @ShayNehmad-RecoLabs, I initially thought something was wrong when I followed the link and saw "NOT ON THE CURRENT EDITION" in a big, bold font. When I first saw that, I wondered, "Why are they linking to a page that doesn't even recommend structured logging anymore." However, that's not actually the case. If you follow a link to the TechRadar's FAQ page, you find this entry under "Why do blips disappear between Radars?":

The Radar represents technologies that are currently on our mind. Given how fast technology is advancing, the default rule is that blips only appear on the Radar for one edition unless they move rings. However, members of the Thoughtworks Technology Advisory Board (TAB) can always make an argument to keep a blip, for example when something noteworthy has happened warranting a refresh of the writeup. Older blips remain searchable under the full A-Z index.

We think it’s important to keep older blips in the index for completeness and visibility, but please be aware that we’re not updating them. In some cases, Thoughtworks teams may continue to work with and recommend these technologies; in others, the advice could be outdated. If you’re looking at a blip from our archive, do keep this in mind. (emphasis added)

Confusingly, I am guessing that they still recommend structured logging, but that they have archived the recommendation because (?!?) structured logging is now so commonly used compared with 2014 and 2015 when it was proposed and then adopted as a recommendation.

Even more weirdly, the current version of the TechRadar page still has all the same text as the version that the README originally pointed to. But, you have to keep reading below the misleading paragraph at the top of the page! If you use the Wayback Machine, you can get a look at the Radar from two days before the README was committed, in May of 2016. The content in 2016 and today (2022) is the same except that now there's a potentially misleading paragraph saying that this idea is "NOT ON THE CURRENT EDITION."

All of that said, if you'd like to update the README with a Wayback Machine link or with a differently worded introduction to that quotation, I'm happy to do it. (Yes, apparently I spent 20 minutes on this because I was confused and then annoyed at the TechRadar website. Happy Saturday?) Thanks for this library.

peterbourgon commented 1 year ago

Better to just remove the link, I think.

telemachus commented 1 year ago

Better to just remove the link, I think.

And the quote as well or leave that? (Compromise and paraphrase the quote? E.g., “Consequently, package log is of the strong belief that structured logging offers great benefits in exchange for minimal effort.”)