И почему вы должны?
Я думаю, что новички, которые немного изучили программирование, должны прочитать официальную документацию, чтобы еще больше улучшить свои навыки.
Официальный документ содержит информацию, необходимую для реализации, например, четко написанные подробные объяснения, как использовать API и примечания к выпуску.
Однако, не так ли много программистов, которые спотыкаются из-за того, что плохо читают официальную документацию? Техническая документация может быть сложной для чтения неопытным пользователям.
В этой статье я напишу о некоторых причинах и мерах противодействия неспособности читать официальные документы, чтобы уменьшить количество людей, которые спотыкаются.
Что такое официальная документация?
«Официальная документация» в этой статье относится к документации фреймворка, библиотеки или языка, опубликованной официальной организацией.
1. Не вижу смысла читать официальные документы
Мне кажется: «В Интернете много технических статей, так что нет необходимости читать официальную документацию, верно?»
Я понимаю это чувство, но, в конце концов, большинство статей — это вторичная информация по официальным документам.
Может быть написано неправильно, или информация может быть устаревшей. Кроме того, было бы сложно найти подробные спецификации API в документах.
Вы не сможете стать полноценным инженером, если будете вечно полагаться на второстепенную информацию. Когда у вас возникают проблемы с реализацией, вам нужно прочитать официальную документацию, чтобы вы могли найти нужную информацию самостоятельно.
Как инженер, заведите привычку проверять первичную информацию.
2. Непонимание общей картины
Прежде чем читать документацию, если вы понимаете, почему язык/фреймворк/библиотека были созданы и что они делают, вы сможете понять это быстрее.
Например, многие статьи легко понять о том, что вы можете делать с React и его преимуществах. Если вы обратитесь к таким статьям, получите обзор, пошевелите руками и получите представление об этом, а затем прочитаете официальный документ, вы сможете понять его с естественным чувством. Я думаю.
Если вы вдруг прочитали официальную документацию и не поняли концепцию, давайте понемногу углублять ваше понимание, обращаясь к обобщающим материалам.
Это означает, что требуется больше, чем просто документы. Эта информация предназначена только для понимания официального документа в простой для понимания форме. Я думаю, что чтение официального документа, основанного на этих основах, необходимо.
3. У меня нет времени читать официальную документацию
Во-первых, чтение официальной документации занимает много времени. Если у вас мало времени из-за работы, вы можете скопировать и вставить информацию из статей. Однако это не улучшит ваши навыки. Вы можете в конечном итоге работать с неправильными знаниями.
Во-первых, важно прочно угнаться за языком и фреймворком. Иногда вы можете попросить их поставить задачу прочитать документацию.
Серьезные люди могут подумать: «Вместо того, чтобы неторопливо читать официальную документацию, я должен быстро внедрить ее и получить результат!» Но наличие твердых знаний может сэкономить вам много времени в долгосрочной перспективе.
Для понимания важно иметь твердое «определение», а не полагаться на «примеры».
Включите свое понимание официальной документации в свою повседневную работу для немедленных результатов и долгосрочной производительности.
4. Нет культуры чтения официальных документов
До этого момента это была проблема на индивидуальном уровне, но я думаю, что и в команде есть аналогичные проблемы.
Если у команды вообще нет культуры чтения официальной документации, будет сложно создать задачу по чтению документации. Читайте статьи и делитесь ценностью чтения официальной документации. Более того.
- Учебная сессия для совместного чтения официальных документов
- Учебная сессия, чтобы жить, чтобы кодировать код, указанный в официальном документе
- Чтение в парах, чтобы поделиться пониманием, читая вместе с наставником
Если вы сможете делать такие вещи, культура постепенно приживется, и команда станет сильнее.
Эти действия могут не дать немедленных результатов, но сначала важно выработать привычку, поэтому наберитесь терпения.
5. Официальный документ не предназначен для чтения
Некоторые фреймворки/библиотеки должны быть написаны, чтобы прочитать официальную документацию, или предоставленная информация часто отсутствует.
В этом случае вы не можете не полагаться на официальную документацию. В этом случае необходимо решить ее самостоятельно, например, «обратиться к проблеме репозитория на Github» или «непосредственно обратиться к коду репозитория».
Если у репозитория много пользователей, люди должны сталкиваться с похожими проблемами, поэтому существует высокая вероятность того, что проблема существует. Тем не менее, если нет, это может быть трудно. Решение этого также является серьезным препятствием, если напрямую обратиться к коду.
В этом случае нет другого выбора, кроме как читать статьи в блогах. Мне жаль, что это не решено.
Однако в последние годы количество документов увеличилось. В частности, Vue.js стал популярным благодаря удобочитаемости официальной документации.
Хорошо разработанная структура имеет хорошую документацию. При выборе технологии учитывайте наличие официальной документации.
Я думаю, что хорошо побуждать людей читать официальную документацию, но у новичков почему-то возникают проблемы с ее чтением. Я написал эту статью, чтобы восполнить этот пробел.
Я надеюсь, что новички смогут использовать эту статью в качестве справочника, чтобы объяснить, почему трудно читать официальную документацию и придумывать контрмеры.
Освойте официальную документацию и станьте сильным инженером, способным конкурировать со всем остальным миром.
Дополнительные материалы на PlainEnglish.io.
Подпишитесь на нашу бесплатную еженедельную рассылку новостей. Подпишитесь на нас в Twitter, LinkedIn, YouTube и Discord .
