3 ms·

It’s still wise to define acronyms before you use them to enable future Googling (links are better!). Three extra words is a small price to pay to make document

by teeray 5y ago

It’s still wise to define acronyms before you use them to enable future Googling (links are better!). Three extra words is a small price to pay to make documentation more friendly to newcomers.

wrycoder 5y ago
I just looked up BGP on DDG. The first ten hits explained it without even clicking on them. If something isn’t clear on HN, try searching for it. If you don’t find it immediately, then you can ask without losing face.
chockchocschoir 5y ago
Again, at one point you have to assume either basic knowledge or at least basic knowledge about how to search for things, otherwise everything would be very verbose. Take one of your repositories as an example: https://github.com/timraymond/pricegrabber https://github.com/timraymond/pricegrabber > A gem for interacting with the Pricegrabber API Should you have to add "Application Programming Interface (API)" the first time you use "API" anywhere? Realistically no, because the audience can be assumed to understand what it means. If they don't, it's only a search away. Same goes for networking and DNS/BGP/CNAME and more. If you're using a library/server for BGP, you either know what those terms are, or know how to find out more. But not all resources are meant for beginning who don't know the basic terms in a field, and that's OK, because otherwise everything would be extremely verbose when it doesn't have to.
- deleted 5y ago
  [deleted]
- spc476 5y ago
  HTML does have the <ABBR> tag. I use it all the time on my blog any time I use an acronym [1]. At least Firefox and Safari will display the title attribute as a tool tip, so hovering over the following HTML: "<abbr title="Border Gateway Protocol">BGP</abbr>" on those browsers will show "Border Gateway Protocol". I'm sad that it's not used more often. [1] An example: http://boston.conman.org/2022/02/16.1 http://boston.conman.org/2022/02/16.1
- 0x20cowboy 5y ago
  Of course, you can do whatever you like, but so far everyone who has thrown up such protest over this has done so by literally writing out definitions to show how hard it would be :-/
  - politician 5y ago
    Does spelling out Border Gateway Protocol even help here?

by teeray 5y ago

It’s still wise to define acronyms before you use them to enable future Googling (links are better!). Three extra words is a small price to pay to make documentation more friendly to newcomers.

wrycoder 5y ago

I just looked up BGP on DDG. The first ten hits explained it without even clicking on them. If something isn’t clear on HN, try searching for it. If you don’t find it immediately, then you can ask without losing face.

chockchocschoir 5y ago

Again, at one point you have to assume either basic knowledge or at least basic knowledge about how to search for things, otherwise everything would be very verbose. Take one of your repositories as an example: https://github.com/timraymond/pricegrabber https://github.com/timraymond/pricegrabber > A gem for interacting with the Pricegrabber API Should you have to add "Application Programming Interface (API)" the first time you use "API" anywhere? Realistically no, because the audience can be assumed to understand what it means. If they don't, it's only a search away. Same goes for networking and DNS/BGP/CNAME and more. If you're using a library/server for BGP, you either know what those terms are, or know how to find out more. But not all resources are meant for beginning who don't know the basic terms in a field, and that's OK, because otherwise everything would be extremely verbose when it doesn't have to.

deleted 5y ago
[deleted]
spc476 5y ago
HTML does have the <ABBR> tag. I use it all the time on my blog any time I use an acronym [1]. At least Firefox and Safari will display the title attribute as a tool tip, so hovering over the following HTML: "<abbr title="Border Gateway Protocol">BGP</abbr>" on those browsers will show "Border Gateway Protocol". I'm sad that it's not used more often. [1] An example: http://boston.conman.org/2022/02/16.1 http://boston.conman.org/2022/02/16.1
0x20cowboy 5y ago
Of course, you can do whatever you like, but so far everyone who has thrown up such protest over this has done so by literally writing out definitions to show how hard it would be :-/
- politician 5y ago
  Does spelling out Border Gateway Protocol even help here?