hyperlinking essential words

[KrishMunot]

No description provided.

[jrose-apple]

Can I ask why this is an improvement? I don't think I've generally seen consistency on this across the internet, and as far as I can see it doesn't make things any clearer.

[KrishMunot]

I thought Apple was very specific when it came to details. And I assumed that highlighting the right word would make it look better.
Comparing ourselves to the internet is not right, Apple has its own reputation for being perfect and attention to minute details. This caught my attention and I was distracted by it. So, lets stick to perfection maybe?

[jrose-apple]

Attention to details is good, but I'm still not clear on why "the website" is wrong and "website" is right. Is there an existing style guide that recommends this?

[mxcl]

I vote to delegate to @mattt

[KrishMunot]

I would definitely not say that "the website" is wrong per se, but aesthetically I believe that when "website" is hyperlinked, it feels that the most relevant keywords have been highlighted, which is a general rule in every style guide.
The addition of "the" to be hyperlinked seems as though very little care was taken during documentation. Two consecutive words are hyperlinked only when they both belong to the same topic (Eg: Apple iPod) or are atleast 2 completely different links. Here, it doesn't match either of the conditions.

[mattt]

@KrishMunot There are currently no formalized conventions on the website with respect to which words to hyperlink. Any lack of internal consistency around usage—such as in the case of this PR—would be better characterized as a variation among individuals rather than any lack of care or attention to detail.

Concerning the convention itself, there are arguments to be made for both including ("website" and "the website" are both noun phrases) and excluding (aesthetics; conciseness) the definite article in the hyperlink text. However, many style guides (like this one) appear to be limited to avoiding the common anti-pattern of "click here", and do not offer further guidance.

If anything, I'd vote to change "the website" to an explicit mention of "Swift.org", as the former is ambiguous (what website? GitHub?).

[KrishMunot]

I totally agree with you @mattt . That was a really good style guide and I really learnt something cool today. I have made a new PR with a relevant keyword which is hyperlinked.
Thanks! :)

[mattt]

@KrishMunot Awesome. Thanks for your contribution! Feel free to close this PR if #206 supersedes it.