Вижте например тази страница:
https://cljuredocs.org/clojure.core/require

Първо, изглежда като някаква зле форматирана проза, определено не като някакъв технически документ, който трябва да предава точни определения.

Но външният вид е само едно, съдържанието е още по-лошо:

„Зарежда библиотеки, като пропуска всички, които вече са заредени.“

Обикновено не бих се захванал с първото изречение, но ако прочетете цялата страница, знаете ли какво няма да намерите?

Няма да разберете какво всъщност е „натоварването“ и какво не е.

Самото нещо, което прави тази функция, вече трябва да разберете, преди да започнете да я използвате. Това е умопомрачително.

Като четем по-нататък, поне можем да разберем какво е „lib“, но по това време мозъкът ми вече е наводнен със следните изрази, които не разбирам: libspec, списък с префикси, общ префикс, флаг, който модифицира, ns макрос. Разбира се, имам някои интуитивни усещания за всичко това, но повече от десетилетие програмиране ме научи дори да не се опитвам да слушам интуицията, когато чета документация, защото тя просто ме подвежда. Така че, за да разбера първия абзац, ще трябва да потърся в Google поне тези пет израза и след това да следвам всеки от тях в заешката дупка. И това е само първият параграф.

Добре, осъзнавам, че ако започна да търся в гугъл, преди да прочета всичко, може да започна да преследвам обясненията, които присъстват на тази страница, така че неохотно чета по-нататък, записвайки всичко, което е необяснено досега за мен: именуван набор, ресурси, класова пътека, Java пакет , споделяне на имена. Освен това, как споделеното име може да намери главната директория на нещо?
Да продължим: classpath-relative, path-mapping, асоциирано пространство от имена (звучи като мафията).

Добре, така че сега виждам, че libspec, флаговете и списъците с префикси също са обяснени до известна степен, това може да е лесно разпознаваема характеристика на тази страница с някакво удобно за хората форматиране. Вместо това всеки път, когато искам да прочета нещо за някое от тези неща, трябва да търся за секунди, опитвайки се да различа сивия текст на сив фон, сякаш играя някаква скучна игра, направена от лош ИИ. Просто искам да знам какво прави изискването. Е, сега знам, че това изисква много библиотеки. Нека потърсим в Google това.

И така, има тази страница https://cljure.org/reference/libs, която е първата в резултатите от търсенето с Google, очевидно много по-добре форматирана, четима от хората страница. Не сте сигурни защо съществува clojuredocs, ако има тази добре форматирана документация? Освен това, ако има няколко документа, ако намеря някои разлики, как да разбера кой е правилният? Ако няма разлики, защо дублираното съдържание?

Четейки документите, нещата започват да се изясняват, но все още не знам какво е зареждане.

Нека го потърсим в Google.

Този път всъщност написвам въпроса, надявайки се да получа някакъв stackoverflow или подобен отговор, защото времето започва да ми изтича и желая нещо, което би повдигнало по-малко въпроси от това колко отговори.

Не виждам подходящи SO въпроси, но първият резултат е тази страница: https://cljuredocs.org/cljure.core/load

Не съм сигурен защо не някои от хубавите документи, но кликвам и откривам, че функцията за зареждане „зарежда код“.

За известно време се взирам в екрана и се замислям дали има някаква причина да се опитам да попитам за това в каналите за поддръжка. Но тъй като последните няколко пъти го направих, ми казаха на „RTFM“ (не буквално, те са мили хора, те говорят с теб по много красноречив начин), отказвам се и решавам, че може би друг ден ще се опитам да разбера това отново.