3 ms·

> Assume readers know the basics or will look them up [...] One of the beautiful things about reading on the internet is that google is just a click away. Espe

> Assume readers know the basics or will look them up [...] One of the beautiful things about reading on the internet is that google is just a click away. Especially in the case of technical jargon, it's a good middle ground to link to a relevant definition directly. That avoids the friction of a suboptimal in-line definition and the friction of forcing a multi-click lookup. A beautiful part of the internet is links :). > Instead of leaving posts as a boring todo chore in the drafts folder, it's perfectly fine to just stop cold and publish if a wrap up doesn't flow naturally. Honestly, nobody cares. While I agree with publishing incomplete content, I would argue that this is an exception to the "Don't caveat, just say it" section from earlier. It's often helpful to caveat incomplete content because it treats the reader with greater respect.

davnicwil 5y ago
> A beautiful part of the internet is links You are right of course and I also always appreciate this when done well! Think you're right it's best used for stuff like technical jargon where very good and specific info can be difficult to find via an open-ended search.
baud147258 5y ago
> > Assume readers know the basics or will look them up [...] One of the beautiful things about reading on the internet is that google is just a click away. > Especially in the case of technical jargon, it's a good middle ground to link to a relevant definition directly. That avoids the friction of a suboptimal in-line definition and the friction of forcing a multi-click lookup. A beautiful part of the internet is links :). I remember one personal website that's been linked on HN (https://www.gwern.net/ https://www.gwern.net/) where hovering links show a preview of the page, a bit like wikipedia is doing, but not limited to the top, where it's possible to scroll up and down. I think a similar system could be interesting when dealing with technical subjects.
- cgriswald 5y ago
  That's a work of art. It works recursively and windows can be pinned, expanded, or closed. You are free to go down the rabbit hole as far as you like and exiting the rabbit hole is a mere cursor movement away.
  - nefitty 5y ago
    It reminds me of the zigzag data structure and Xanadu project. I try to emulate these sorts of ui's in my own experiments. It feels more intuitive, spatially.
- maxwelljoslyn 5y ago
  Gwern is love, Gwern is life.
stavros 5y ago
I wanted a way to write both for people who were familiar with terms and for people who weren't, so I made Expounder: https://skorokithakis.github.io/expounder/ https://skorokithakis.github.io/expounder/
- spurgu 5y ago
  This is brilliant! I completely agree with the premise: > I would frequently be familiar with one part of the source material, but have no way to skip it and only read the parts I was unfamiliar with. This makes for so much cleaner articles. It's actually a bit similar to what waitbutwhy.com is doing with tooltips. It might have some negative SEO implications (if you're worried about that) because if you hide a lot of content like that it could potentially be seen by search engines as keyword stuffing[0]. But if SEO is a secondary concern (which it should be for reasonable people not obsessed about rankings) then this is an excellent solution. Would love to see this more widely adopted. [0] While a 2k word article explaining something that could be explained in 200 words is not :facepalm:
rsync 5y ago
"Assume readers know the basics or will look them up ..." I am taking a different approach with a new form I am experimenting with - the "Iceberg Article": https://john.kozubik.com/pub/IcebergArticle/tip.html https://john.kozubik.com/pub/IcebergArticle/tip.html The idea is that there are two complete treatments of the subject - the "tip" which is highly compressed and the "body"[1] which is fleshed out with notes, pictures, examples, subscripts, etc.: "In this way, a concise and complete treatment of a subject can serve as a gateway to an extremely deep and rich well of content that does not distract from the parent work." [1] Yes, I did start off properly referring to it as a "bummock" but I got sick of both reading and writing that word.
- spurgu 5y ago
  FYI getting a certificate error there.
- maxwelljoslyn 5y ago
  Always happy to see someone writing in a hierarchical format. Maybe one day everyone will wake up and start writing Engelbart-style tree documents[1]. Site feedback for you, John: I would appreciate if you linkified your name (in the header of the page), as well as the path "breadcrumbs" at the right hand side of the header. Otherwise I'm stuck chopping things out of the URL by hand to try and go up the path. [1] For instance, see this online copy of "Augmenting Human Intellect" (AHI). https://dougengelbart.org/content/view/138/ https://dougengelbart.org/content/view/138/ Notice how all the paragraphs are explicitly arranged in a hierarchy. At Engelbart's research lab, all documents were circulated in such a format ... even public releases like AHI ... and they had software with capabilities similar to today's org-mode, or Workflowy, or Vim folds which let researchers browse/edit code and text with respect to the hierarchy ... I highly recommend reading the linked report.
is0tope 5y ago
Recently I've got into the habit of doing both. Typically if there is a topic that is important to understand for a casual reader, but likely will be obvious for someone familiar with the topic i add a "click here to skip" link. I haven't actually measured how often this is used, so it's hard to guage effectiveness, but I think it at least suggests to readers that you are trying to respect their time. An example from my blog about price wicks, explaining how candlestick charts work: https://www.machow.ski/posts/scamwicks-and-stop-cascades/#candlestick-chart-intro https://www.machow.ski/posts/scamwicks-and-stop-cascades/#ca...
- Tomte 5y ago
  A <details> tag is also very nice for that.
asiachick 5y ago
> Assume readers know the basics or will look them up [...] One of the beautiful things about reading on the internet is that google is just a click away That doesn't fit my experience writing programming tutorials at all. The people reading them will not "google it". they'll just get confused that you didn't explain everything and they therefore got lost. Certainly the top of the article lists pre-recs and links to them but it's surprising how many people will read lesson number 15 of 40 and skip lessons 1 through 14 and then complain that they didn't understand it. I end up having to spell it out. Bla bla bal (which we covered in lesson 3), does bla bla bla (covered in lesson 7) etc....

davnicwil 5y ago

> A beautiful part of the internet is links You are right of course and I also always appreciate this when done well! Think you're right it's best used for stuff like technical jargon where very good and specific info can be difficult to find via an open-ended search.

baud147258 5y ago

> > Assume readers know the basics or will look them up [...] One of the beautiful things about reading on the internet is that google is just a click away. > Especially in the case of technical jargon, it's a good middle ground to link to a relevant definition directly. That avoids the friction of a suboptimal in-line definition and the friction of forcing a multi-click lookup. A beautiful part of the internet is links :). I remember one personal website that's been linked on HN (https://www.gwern.net/ https://www.gwern.net/) where hovering links show a preview of the page, a bit like wikipedia is doing, but not limited to the top, where it's possible to scroll up and down. I think a similar system could be interesting when dealing with technical subjects.

cgriswald 5y ago
That's a work of art. It works recursively and windows can be pinned, expanded, or closed. You are free to go down the rabbit hole as far as you like and exiting the rabbit hole is a mere cursor movement away.
- nefitty 5y ago
  It reminds me of the zigzag data structure and Xanadu project. I try to emulate these sorts of ui's in my own experiments. It feels more intuitive, spatially.
maxwelljoslyn 5y ago
Gwern is love, Gwern is life.

stavros 5y ago

I wanted a way to write both for people who were familiar with terms and for people who weren't, so I made Expounder: https://skorokithakis.github.io/expounder/ https://skorokithakis.github.io/expounder/

spurgu 5y ago
This is brilliant! I completely agree with the premise: > I would frequently be familiar with one part of the source material, but have no way to skip it and only read the parts I was unfamiliar with. This makes for so much cleaner articles. It's actually a bit similar to what waitbutwhy.com is doing with tooltips. It might have some negative SEO implications (if you're worried about that) because if you hide a lot of content like that it could potentially be seen by search engines as keyword stuffing[0]. But if SEO is a secondary concern (which it should be for reasonable people not obsessed about rankings) then this is an excellent solution. Would love to see this more widely adopted. [0] While a 2k word article explaining something that could be explained in 200 words is not :facepalm:

rsync 5y ago

"Assume readers know the basics or will look them up ..." I am taking a different approach with a new form I am experimenting with - the "Iceberg Article": https://john.kozubik.com/pub/IcebergArticle/tip.html https://john.kozubik.com/pub/IcebergArticle/tip.html The idea is that there are two complete treatments of the subject - the "tip" which is highly compressed and the "body"[1] which is fleshed out with notes, pictures, examples, subscripts, etc.: "In this way, a concise and complete treatment of a subject can serve as a gateway to an extremely deep and rich well of content that does not distract from the parent work." [1] Yes, I did start off properly referring to it as a "bummock" but I got sick of both reading and writing that word.

spurgu 5y ago
FYI getting a certificate error there.
maxwelljoslyn 5y ago
Always happy to see someone writing in a hierarchical format. Maybe one day everyone will wake up and start writing Engelbart-style tree documents[1]. Site feedback for you, John: I would appreciate if you linkified your name (in the header of the page), as well as the path "breadcrumbs" at the right hand side of the header. Otherwise I'm stuck chopping things out of the URL by hand to try and go up the path. [1] For instance, see this online copy of "Augmenting Human Intellect" (AHI). https://dougengelbart.org/content/view/138/ https://dougengelbart.org/content/view/138/ Notice how all the paragraphs are explicitly arranged in a hierarchy. At Engelbart's research lab, all documents were circulated in such a format ... even public releases like AHI ... and they had software with capabilities similar to today's org-mode, or Workflowy, or Vim folds which let researchers browse/edit code and text with respect to the hierarchy ... I highly recommend reading the linked report.

is0tope 5y ago

Recently I've got into the habit of doing both. Typically if there is a topic that is important to understand for a casual reader, but likely will be obvious for someone familiar with the topic i add a "click here to skip" link. I haven't actually measured how often this is used, so it's hard to guage effectiveness, but I think it at least suggests to readers that you are trying to respect their time. An example from my blog about price wicks, explaining how candlestick charts work: https://www.machow.ski/posts/scamwicks-and-stop-cascades/#candlestick-chart-intro https://www.machow.ski/posts/scamwicks-and-stop-cascades/#ca...

Tomte 5y ago
A <details> tag is also very nice for that.

asiachick 5y ago

> Assume readers know the basics or will look them up [...] One of the beautiful things about reading on the internet is that google is just a click away That doesn't fit my experience writing programming tutorials at all. The people reading them will not "google it". they'll just get confused that you didn't explain everything and they therefore got lost. Certainly the top of the article lists pre-recs and links to them but it's surprising how many people will read lesson number 15 of 40 and skip lessons 1 through 14 and then complain that they didn't understand it. I end up having to spell it out. Bla bla bal (which we covered in lesson 3), does bla bla bla (covered in lesson 7) etc....