Проверьте, например, эту страницу:
https://clojuredocs.org/clojure.core/require
Во-первых, это похоже на какую-то плохо отформатированную прозу, а не на какой-то технический документ, который должен давать точные определения.
Но внешний вид — это одно, содержание — еще хуже:
«Загружает библиотеки, пропуская уже загруженные».
Обычно я бы не стал придираться к самому первому предложению, но если вы прочитаете всю страницу, знаете, чего вы не найдете?
Вы не узнаете, что такое «нагрузка» на самом деле, а что нет.
То, что делает эта функция, вы уже должны понимать, прежде чем начать ее использовать. Это сбивает с толку.
Читая дальше, по крайней мере, мы можем узнать, что такое «lib», но к тому времени мой мозг уже забит следующими выражениями, которые я не понимаю: libspec, список префиксов, общий префикс, флаг, который модифицирует, макрос ns. Конечно, у меня есть некоторые интуитивные чувства ко всему этому, но более десяти лет программирования научили меня даже не пытаться прислушиваться к интуиции при чтении документации, потому что она просто вводит меня в заблуждение. Поэтому, чтобы понять первый абзац, мне нужно было бы найти в Google хотя бы эти пять выражений, а затем проследить каждое из них по кроличьей норе. И это только первый абзац.
Хорошо, я понимаю, что если я начну гуглить, не прочитав всего, я могу начать гоняться за пояснениями, которые присутствуют на этой странице, поэтому я неохотно читаю дальше, записывая все, что мне пока непонятно: именованный набор, ресурсы, путь к классам, пакет Java , обмен именами. Кроме того, как общее имя может найти корневой каталог чего-либо?
Продолжим: относительный путь к классам, сопоставление путей, связанное пространство имен (звучит как мафия).
Итак, теперь я вижу, что libspec, флаги и списки префиксов также в некоторой степени объяснены, это могло бы быть легко узнаваемой особенностью этой страницы с некоторым удобным для человека форматированием. Вместо этого каждый раз, когда я хочу прочитать что-нибудь о любой из этих вещей, мне приходится искать в течение нескольких секунд, пытаясь различить серый текст на сером фоне, как будто я играю в какую-то скучную игру, созданную плохим искусственным интеллектом. Я просто хочу знать, что требуется. Что ж, теперь я знаю, что требуется загрузка библиотек. Давайте погуглим это.
Итак, вот эта страница https://clojure.org/reference/libs, которая стоит первой в результатах поиска Google, явно лучше отформатирована, удобочитаемая страница. Не знаете, зачем существует clojuredocs, если есть эта красиво отформатированная документация? Кроме того, если есть несколько документов, если я найду какие-то различия, как узнать, какой из них правильный? Если нет различий, то зачем дублированный контент?
Читая документы, вещи начинают проясняться, но я до сих пор не знаю, что такое загрузка.
Давайте погуглим.
На этот раз я на самом деле записываю вопрос, надеясь, что получу какой-нибудь ответ на stackoverflow или аналогичный ответ, потому что у меня заканчивается время, и я хочу чего-то, что вызовет меньше вопросов, чем на то, сколько ответов.
Я не вижу соответствующих вопросов SO, но первым результатом является эта страница: https://clojuredocs.org/clojure.core/load
Не уверен, почему не некоторые из хороших документов, но я щелкаю и узнаю, что функция загрузки «загружает код».
Некоторое время я смотрю на экран и размышляю, есть ли смысл пытаться спросить об этом на каналах поддержки. Но из-за того, что в последние несколько раз я сделал это, мне сказали «RTFM» (не буквально, они милые люди, они очень красноречиво разговаривают с вами свысока), я сдаюсь и решаю, что, может быть, в другой раз я попытаюсь понять это. снова.
