Show HN: Expounder – A small JavaScript library for more engaging tutorials | Hacker News Reader

Show HN: Expounder – A small JavaScript library for more engaging tutorials

skorokithakis.github.io

134 pointsstavros48 comments

My advice would be to somehow indicate exactly the text that was expounded - maybe with a faint underline or something. When it expands out, it's sometimes difficult to track the exact words that suddenly appear.

and add an option to re-collapse the text

That's another feature that's requested a lot. I'm still not convinced that it's something people request because they actually want to re-collapse the text or just because they're used to the mechanic of "if it expands, it must contract". Presumably they wouldn't feel the need to collapse a paragraph that they didn't expand first, even if it was the exact same paragraph.

It throws off my reading if I'm just checking that I know what something is and only need a quick skim to verify that. I immediately lost track of what was the explanation and what was the original text.

The idea is that you don't need to keep track of what's what, it's all original text. Why did you feel you had to distinguish?

Can't speak for GP, but I experienced a similar moment of "ok now how do i close this again" before realizing I didn't really need to. But that didn't feel quite right either, like a popup that won't go away once its purpose has been served. Or like checking a footnote, and having a hard time finding my way back to wherever it was referenced. I get that what this library does isn't quite either of those things, but it feels enough like both of them that not being able to un-expound feels a little weird.

I've actually been thinking about doing the same thing in a side project of my own, and while I think you're somewhat correct, I don't think this is all necessarily attributable to affinities for symmetry.

For instance, if you convey a concept, and then show the derivation of the equation for that - the derivation mostly does not matter in the communication of the concept. Sure it's important to understand this, thus why we always have the derivation, but often it adds cognitive weight that distracts from the more germane understanding of the material (so keen authors will try and be elegant about the complicated things, skipping steps and keeping as much on one page).

It takes up cognitive load, and often a different type of load than the big picture. By collapsing the content, you get back to the more pure "short version" of the material and you can presume to understand or trust the more complicated bits that are hidden away.

I see what you mean, but why does it matter? By the time you've read the explanation, you've moved past it, and no additional action is necessary, it's just of no interest to you any more, like the rest of the text you've read. Adding a collapsing mechanic would "require" you to take action again by collapsing the thing, even though you will never return to see it.

There are a few things:

Even if it's not that useful, it's what I expect to happen without thinking. Having no "undo" makes me wonder what happened and a vague fear that I've done something destructive. More personally, it just feels a bit weird with the way I jump back and forth in documents as everything moves. I can't quite explain it but it feels quite weird.

> By the time you've read the explanation, you've moved past it

The explanations/diagrams don't appear immediately after/over what I click. So I click for extra info, jump over some intermediate text and read the extra stuff then I want to go back to the normal flow. Look at 'atoms' and 'photons' in the example text: https://skorokithakis.github.io/expounder/

There are other examples of this too, in your original blog post about building the sensor. Look for examples where the extra explanatory text appears in a paragraph after what you click on.

> I can't quite explain it but it feels quite weird.

I definitely know what you mean, but it's a problem with me being compulsive about having opened things stay open, not with the things themselves :P

> So I click for extra info, jump over some intermediate text and read the extra stuff then I want to go back to the normal flow.

I think that's the best argument so far. However, I think this is the "footnote" mindset (i.e. you go look up what the footnote is and come back). Expounder works under a more integrated mindset, i.e. "I don't know what this is, I click it and I will eventually read information about it". So you don't go read the expounded text and come back, you just read normally, and you reach the text at some point.

Then it's a matter of whether it's easier to change the user or the library, but that's how I meant it originally.

> I definitely know what you mean, but it's a problem with me being compulsive about having opened things stay open, not with the things themselves :P

I disagree, it's not about leaving things open. It's that I skip back and forth while reading and this moves a bunch of text. Suddenly, some things I was moving back and forth between have either gone or moved and it's not obvious which.

> I think that's the best argument so far. However, I think this is the "footnote" mindset (i.e. you go look up what the footnote is and come back). Expounder works under a more integrated mindset, i.e. "I don't know what this is, I click it and I will eventually read information about it". So you don't go read the expounded text and come back, you just read normally, and you reach the text at some point.

Fair enough that it's built for a different use. I find it very hard to have an animation happen near where I'm looking but entirely ignore it, so I'll look over to see what's happened.

> By the time you've read the explanation, you've moved past it

Not with dense material. Often, I'll read through a chapter quickly, then go through the derivation of something three or four times until I understand it deeply, then re-read the chapter again once or twice to fully grasp it (at which point the derivation is just taking up space and I want to understand the grander scheme). Granted, I'm applying my approach to upper-division to grad-level physics textbooks, but that's the extreme I'm personally hoping to make more approachable for people.

One place collapsing would be useful is if the revealed text turns out not to be what I was expecting. E.g. maybe I thought clicking Planck's constant would reveal a number or equation.

On the other hand, I could see the extra mechanic leading me to try to "curate" the article, which would distract from the actual content. There is definitely value in keeping it simple.

Very nice library!

I think that the "no collapse" thing is the right way to go. It's simpler, and really no cognitive load... you can ignore any text in the article you want :-).

Also, when you go back to the page, it's all collapsed again anyway, so the next time you read it, you don't need the expounded bits, and it's all compact.

It's also just prettier to not have a bunch of lurking controls.

Thank you! I think so too. We implemented it, after multiple requests, but I dislike it so much that I decided to not put it in the documentation. It's there if an author chooses to use it, but I'd prefer them not to!

Ah, good idea. Right now you get a fade, but that's easy to miss. Of course, the intent is that the expounded text becomes a part of the overall paragraph, so you shouldn't need to know what was just expounded, you just read on, so there's definitely a balance there.

Also, the text is very very easy for the website owner to style, with just a single CSS rule.

EDIT: I've added some styling information to the page, thanks.

This is the first time i heard about https://gitcdn.xyz/ while checking your page source.

That's actually a smart idea for a CDN :)

Yep! We were using rawgit initially, but it went down on the first day for hours, so we changed to that instead.

Or maybe just use a popup, not sure if inlining it is better.

Exactly, I was thinking that something like the XKCD What-If notes would be easier on the reader and the writer.

Interesting. I personally like to use sidenotes for this type of thing on my website; it's nice to be able to scan the sidenotes for additional info without clicking on anything. On the other hand, they really don't work on mobile. BigfootJS[0] is the nicest footnote-inliner I know of that also works gracefully on small screens (unpaginated media); if you haven't seen it, take a look.

Feedback for this library:

- It would be cool if you could set a few preset levels of expansion (TL;DR, expert, beginner, ELI5) and toggle them at the top of the page.

[0] http://www.bigfootjs.com

Thanks for the feedback, the tiered approach is also something I considered, although with a different method. You would tag things with a number from 1 for outermost to N for innermost and then let the user expand to the specific level. I haven't yet tried that concept, but I probably will soon!

This is an old idea in Hypertext called Stretch Text (since 1967!):

https://en.wikipedia.org/wiki/StretchText

Every so often someone hears about the old hypertext theory and implements a Javascript or CSS version, but this is honestly one of the nicest implementations I've ever seen. Good work!

This seems like something that could impact the nature of composition. I wonder if writers would write differently if they knew they could "expound".

Surely if you write with expounding in mind you'll take that into consideration in your text. You DO write the expanded text after all...

No, I don't believe I do. I think this could be implemented into a blogging platform— a new medium.

Lol yeah, I feel like I want more examples to read. Easy way to filter data you already know. I think I could learn so much faster with this if texts are written properly.

I used it in "normal" usage here:

https://www.stavros.io/posts/building-cheap-home-sensorcontr...

EDIT: I've added a "real-world examples" section to the page with the above included.

Agreed. This could be very powerful.

I've at times been called wordy. But I am fastidious when it comes to diction. If the word is there— it's there for a reason.

I'd love a way to fold.

Actually, that would be a great idea. I think I might write a small thing to integrate it into Pastery (https://www.pastery.net/), maybe with a Markdown extension. It might even become its own service down the line.

(As someone who can't write concisely (without inserting a lot of (unnecessary) context)) I would love (to use) an automated version ((of this) so I can just write with full context (and let people choose the level of details they want (to read))).

I would love an automated version.

Wouldn't a tooltip give the same information while taking up less space and not messing up your carefully setup layout?

Very nice, reminds me of telescopictext.

Here's an example that explains magnetic fields: http://www.telescopictext.org/text/pFjkqQY9bmfvQ

That's pretty much the same context, but I think the demo is lacking. For example, clicking on "magnetic" replaces it with "B", which confuses me even more. There's also at one point a link on "be", which is just baffling. What is there to explain about "be"?

Fully agree. Your semantics of "expounder" and "expounded" spans is much more coherent.

It's a new modality, but I think it has a lot of potential: I love explanations with "multiple levels" in general...

I feel like this could be a really interesting tool for wikis. It'd be neat to be able to read what is, essentially, an executive summary of a topic, but then be able to drill down into a path of discovery that you're interested in.

That's one of the reasons I developed this. You could essentially go into as much detail as you wanted in the topic you wanted. Of course, the writer must be careful not to overdo it, because sometimes the reader does want to just read everything, but it'd be great for things a reader might be familiar with, or that not everyone will find interesting.

Yeah, nice work! I dig it.

Reminds me a little of what Wait But Why is doing in his articles - e.g: http://waitbutwhy.com/2016/03/cryonics.html (look for "New to WBW? Open these.")

(Click -> Tool tip) works better IMO. The sudden append of words threw off my reading rhythm.

I've used something similar for talking about complex code examples. You can show only the current line you're talking about, but have a button to expand out the full example. it's pretty great. Excited to give this a try!

How does a screen reader handle that ?

I'm not sure (I'd appreciate some feedback by someone who uses one), but I'd think it would just read the whole text. Depends on what it does with hidden text.

I recommend reading https://en.wikipedia.org/wiki/WAI-ARIA

Great, a nice little used UI pattern. Now when will my Expounder Wikipedia viewer come?

Very nice and clever. I like it it fits seamlessly into the text.

I knew that name looked familiar! Small world.

Haha, you bastard :P

Reply on news.ycombinator.com