Hacker News Reader

Comment by mikejulietbravo | Hacker News Reader

not a criticism here, just a genuine question. What about this makes it friendly for ADHD? Is it a formatting/style thing? Information ordering?

View on HN

Diagnosed with ADHD here, there's nothing ADHD friendly about this imo. I'm REALLY into reverse engineering content and I just bounced right off the GIANT WALL of text at the beginning.

It's presented in a highly linear conversational fashion but the data doesn't appear to need to be linear. I absorb things in a non-linear fashion (I jump around, sometimes I even read/skim things backwards and out of order.) So it could easily be made ADHD friendly with clear delineation between ideas. A really simple way to do this would be surrounding definition blocks with a slightly lighter background color box and sticking strictly to necessary data, not using conversational language.

Also the color scheme sucks (or rather is non-functional at least to me.). The blue text words really stick out, but the white bold text is what's important. However it also matches with the headers since they seem to be the same font and color, it's really distracting for some reason. Under assembly instructions specifically: like all I see is "value, register, destination, source, destination, expression, destination, destination, destination,..." literally the least important information is highlighted.

The sidebar on the left is distracting too and pulls my eye constantly.

Equating Beginner with ADHD is also mildly offensive and defeats the point if this is targeted at people suffering from ADHD. People with ADHD dive head first in the deep end or not at all, no exceptions. If it's labelled beginner/for-dummies, I'm skipping it or at best skimming it (like i did with this).

ADD/ADHD diagnosed for >30 years now and I was actually curious if some new ADHD friendly web format had been discovered after my years in web engineering, turns out the answer is no.

Like most accessibility issues, this cannot be solved with a format, only with care on the author’s behalf.

The chunking and labeling of concise, strictly topical content and illustrative examples rather than having paragraph-after-paragraph of exposition is a huge factor for my flavor of ADHD, though we're obviously not a monolith. For contrast, lots of folks love the expository format of the Python docs which explains a lot about why things work rather than simply how they work, but that setup is absolutely murder for me. My brain is screaming at me after skimming the first two paragraphs to see if I'm even looking at the right doc, and I'm hitting google or stack overflow 3 seconds later. It's not a good strategy-- I definitely consider it a shortcoming-- but other doc systems work much better for me. For example:

C# regex docs: https://learn.microsoft.com/en-us/dotnet/api/system.text.reg...

Java regex docs: https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pa...

JS regex docs: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe...

PHP preg_replace docs: https://www.php.net/manual/en/function.preg-replace.php

Python regex docs: https://docs.python.org/3/howto/regex.html

Which one of these is not like the others? The Python docs are brilliant for people that click with that style, and as we can see from this well-shared and very controversial piece, (http://cryto.net/~joepie91/blog/2013/02/19/the-python-docume...) suck for others.

Edit: As usual when the Python docs usability is questioned, cue the "well I've got ADHD and I just LOVE the Python docs" (said in the voice of the 'Well I LOVE SPAM' guy from the Monty Python skit). Sure, but you aren't some sort of standard by which others are measured.

Thanks for pointing this out. I had never really thought much about it. I 100% agree with you! The docs are totally why Python is so comfortable for me.

I know so many people that so love them, and I do find the content useful sometimes... but I wish they could be modified a bit to have the deep dive after the really concise reference sheet style doc.

But almost any time I've seen them discussed, even intimating that they're not ideal in their current state is an open invitation to summoning the online equivalent to a pitchfork-wielding crowd implying you're incompetent, lazy, and stupid for having a different usage style. I'm sure there are a lot of people involved who want nothing more than for them to be as useful as possible to everyone who needs them, but those toxic dynamics emerge so quickly in critique. It would obviously be a huge mistake to simply remove that info, but I think the format could be enhanced to work well with other usage styles.

(C# documentation tends to have both types, the API description itself, and expository articles that introduce you to it e.g. https://learn.microsoft.com/en-us/dotnet/standard/base-types... )

As much as they annoy me, I think MS doesn't get enough credit for their dev docs. MDN has some more expository docs in addition to their great reference pages, too. They're super useful, but having them combined can be a real struggle for folks that have difficulty harnessing their attention.

Given the context of conversation, just noting that I too have ADHD and writing in C# has been definitely more doable than dynamically typed languages (or languages that require a lot of code to express something LINQ allows me to do in 1 or 2 lines, like Go). And as long as you know the type for the feature you need, you can usually just write e.g. "Regex" and press `.` and the VS Code or any other IDE of your choice will show you the list of supported methods - most of them are really straightforward to use. It works really well and knowing I don't have to perform much of work to ensure what amounts to type safety manually, or write additional tests, has been really helpful.

More on C# Regex, extra props for source-generated Regexes also generating documentation to explain the exact pattern and how it is matched similar to how websites like regexr do it.

I despise python documentation for this reason. When I want to reference the docs on how to do something I have to cut through huge paragraphs of unorganized and unstructured text to just find out how to do something. It doesn’t help that different builtin modules use different documentation layouts and formatting either.

Yeah I can see why a lot of people love it, but it's fundamentally anathema to the way I use docs. Considering how common other reference formats are, I can't imagine it's rare among developers, but I'm not sure. I'd love to do a usability study. Modern accessibility guidelines implore taking neurological differences into account with web content, but if it's not easily measurable or even a bit subjective, it's not going to get budgeted for in most cases. I imagine without expert advice, even gauging whether or not you've got the right approach is difficult.

At least for me: short sections with emoji, varied formatting, etc provide anchors for me when I loss focus and come back.

IDK. I think sometimes people lean into the idiosyncrasies of their own ADHD. I have ADHD, but I get sucked into writing code because it lets me focus in a way that dishes and laundry do not.

> What about this makes it friendly for ADHD?

Maybe because each section is short and straight to the point?

Isn’t it just friendly for any human?

Another way to look at this is that a lot of content is not well organized.

For some people, this is an inconvenience. For some people, this makes the content impenetrable.

In a learning context, most people benefit from better organization and concision. Some people benefit significantly more than others, and they’re called out here.

Some people are definitely turned off by a terse writing style. If nobody enjoyed long and verbose writing why is there so much of it?

For the record I do think putting ADHD friendly in the title is a little silly.

Reply on news.ycombinator.com