12 ms·

It is unfortunate that you have to read the footnotes to understand the article - on a first read of the text I was completely lost. This is, though, a good id

It is unfortunate that you have to read the footnotes to understand the article - on a first read of the text I was completely lost. This is, though, a good idea - at the moment, many interesting articles are lost because not enough people visit the new page.

ColinWright 13y ago
> It is unfortunate that you have to read the footnotes > to understand the article - on a first read of the text > I was completely lost. I'm not the author, but I'm intensely interested in effective communication. You've taken the trouble to comment, and I was wondering if you'd be willing to walk through the item and explain where you got to in the main body that you thought was unclear, and where you were lost. I assume the first paragraph was self-evident - where did you find it started to become impossible to follow? > ... at the moment, many interesting articles are lost > because not enough people visit the new page. I've always done this, but it's becoming increasingly pointless. My impression is that the number of really interesting articles remains roughly constant, but the total volume increases. It's getting more and more depressing to wade through the uninteresting (to me) to find the rare gems. I still do it though.
- tehwalrus 13y ago
  The first three are in English, sure, I'm talking about the last two paragraphs. I understood the problem, almost from the title - I was interested mostly in the proposed solution. In particular, the last 2-3 sentences where a complex procedure is defined in a few inline code snippets - and then the author continues as if the result is obvious. It reminds me very much of when I read overly mathematical scientific publications (which I do a lot, being a PhD student.) In such papers, the authors often expect you to stop and spend 5 minutes reading a few symbols (perhaps reading a couple of Wikipedia articles along the way) before continuing. This makes the articles highly unreadable - I sometimes spend 2-3 days slowing working through the particularly poor ones. (Obviously, I only do this for highly relevant/useful papers!) This article isn't in the same level of awful, obviously, but it did give me the same "I'm lost now, I should go back" feeling - which I thought was worth feeding back to the author, especially since they had provided the explanation, but they'd hidden it in a footnote.
  - ColinWright 13y ago
    The fact that you're a PhD student might help to explain this. My experience is that most people just won't care, but will be reassured by seeing real code in the text. They will skim without understanding, but getting the idea that there is a concrete process being explained. You (somewhat like me in this instance) will want to understand what's actually happening. For that case the author has in fact provided more detail, relegated to a footnote. You decry this, but you (and I) are in a significant minority in this instance. We want to understand it properly, but I suspect the vast majority or readers won't. Or if they do, not yet. Your comment is useful, and I will keep it in mind next time I write something. For reference, when I want to tuck away technical details I do it in side-bars so it's there to be read alongside the main text. Here: * http://www.solipsys.co.uk/HowHighTheMoon.pdf http://www.solipsys.co.uk/HowHighTheMoon.pdf * http://www.solipsys.co.uk/new/TheBirthdayParadox.html http://www.solipsys.co.uk/new/TheBirthdayParadox.html
    - tehwalrus 13y ago
      Your paper (the first one is as far as I got) is much better, since it just states a simple equation which is typeset separately ("in display mode", in LaTeX-speak) with the derivation for the equation in a sidebar and a note inline in the text pointing it out. This reads like a normal human speaking, who was asked a question and elaborated. That's fine. The problem with the OP's article was that I couldn't skim read it, because the code didn't make obvious sense in a "reading aloud" kind of way. It would have worked much better if the footnote had replaced, or been included as padding around the code. The skim readers would still have been happy, especially if there was a carefully placed paragraph break so they could "skip over the details," and I/we would have been happy too. Also, two code snippets out of context are anything but real code, at least in my brain :)

ColinWright 13y ago

> It is unfortunate that you have to read the footnotes > to understand the article - on a first read of the text > I was completely lost. I'm not the author, but I'm intensely interested in effective communication. You've taken the trouble to comment, and I was wondering if you'd be willing to walk through the item and explain where you got to in the main body that you thought was unclear, and where you were lost. I assume the first paragraph was self-evident - where did you find it started to become impossible to follow? > ... at the moment, many interesting articles are lost > because not enough people visit the new page. I've always done this, but it's becoming increasingly pointless. My impression is that the number of really interesting articles remains roughly constant, but the total volume increases. It's getting more and more depressing to wade through the uninteresting (to me) to find the rare gems. I still do it though.

tehwalrus 13y ago
The first three are in English, sure, I'm talking about the last two paragraphs. I understood the problem, almost from the title - I was interested mostly in the proposed solution. In particular, the last 2-3 sentences where a complex procedure is defined in a few inline code snippets - and then the author continues as if the result is obvious. It reminds me very much of when I read overly mathematical scientific publications (which I do a lot, being a PhD student.) In such papers, the authors often expect you to stop and spend 5 minutes reading a few symbols (perhaps reading a couple of Wikipedia articles along the way) before continuing. This makes the articles highly unreadable - I sometimes spend 2-3 days slowing working through the particularly poor ones. (Obviously, I only do this for highly relevant/useful papers!) This article isn't in the same level of awful, obviously, but it did give me the same "I'm lost now, I should go back" feeling - which I thought was worth feeding back to the author, especially since they had provided the explanation, but they'd hidden it in a footnote.
- ColinWright 13y ago
  The fact that you're a PhD student might help to explain this. My experience is that most people just won't care, but will be reassured by seeing real code in the text. They will skim without understanding, but getting the idea that there is a concrete process being explained. You (somewhat like me in this instance) will want to understand what's actually happening. For that case the author has in fact provided more detail, relegated to a footnote. You decry this, but you (and I) are in a significant minority in this instance. We want to understand it properly, but I suspect the vast majority or readers won't. Or if they do, not yet. Your comment is useful, and I will keep it in mind next time I write something. For reference, when I want to tuck away technical details I do it in side-bars so it's there to be read alongside the main text. Here: * http://www.solipsys.co.uk/HowHighTheMoon.pdf http://www.solipsys.co.uk/HowHighTheMoon.pdf * http://www.solipsys.co.uk/new/TheBirthdayParadox.html http://www.solipsys.co.uk/new/TheBirthdayParadox.html
  - tehwalrus 13y ago
    Your paper (the first one is as far as I got) is much better, since it just states a simple equation which is typeset separately ("in display mode", in LaTeX-speak) with the derivation for the equation in a sidebar and a note inline in the text pointing it out. This reads like a normal human speaking, who was asked a question and elaborated. That's fine. The problem with the OP's article was that I couldn't skim read it, because the code didn't make obvious sense in a "reading aloud" kind of way. It would have worked much better if the footnote had replaced, or been included as padding around the code. The skim readers would still have been happy, especially if there was a carefully placed paragraph break so they could "skip over the details," and I/we would have been happy too. Also, two code snippets out of context are anything but real code, at least in my brain :)