Kristian Glass - Do I Smell Burning?

Mostly technical things

Link for context and not as content

The web is great. Hyperlinks are great. Being able to link to another relevant resource is great.

Please though, link for context not as content

Linking as content:

A: “How come we’re doing Y now?” B: “Because”

Now A needs to go follow the URL to get an answer

Compare with linking for context:

B: “We used to do X, but it had reliability issues for some of our customers - check out”

Don’t use a URL as your answer, comment, explanation etc.; use it as a supplementary aid. “Don’t Repeat Yourself” is for code, not for information.

If your content is just a link, you’re forcing the reader to go elsewhere to understand. Nobody wants to have half a dozen browser tabs open just to follow a comment thread.

URLs break; sites reorganise, posts get deleted, domains expire, and more. Nobody wants to sit there cursing at a comment that just says “Important! See #1234” in a project that has changed issue trackers twice during its history.

Write content that stands alone, and use links elsewhere to give optional context. Future readers will thank you.