[chefandy]

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.

[jdnier]

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.

[chefandy]

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.

[neonsunset]

(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... )

[chefandy]

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.

[neonsunset]

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.

[__turbobrew__]

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.

[chefandy]

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.