Как сделать документацию более удобной для чтения

Если вы задаете вопросы, на которые можно быстро ответить с помощью документации, реакция людей будет зависеть от атмосферы места, в котором вы задаете вопрос, команды, с которой вы работаете, или онлайн-форума. Дружелюбные дадут вам ссылки, где вы можете найти свои ответы. Менее дружелюбные предоставят вам «RTFM» — прочитайте руководство *cough Friendly* — или дадут ссылку на «Позвольте мне погуглить это для вас».

Вы должны попытаться избежать этого. Давайте посмотрим, как вы можете развить навык чтения документации!

Документация: Используйте это

Самое главное, просто начните пытаться получить ответы из документации, когда вы боретесь с вещами. Самым значительным преимуществом чтения документации является то, что вы часто найдете там свой ответ. Вам просто нужно погрузиться в него и найти его самостоятельно. По мере продвижения по карьерной лестнице вы будете находить все больше и больше проблем, готовых руководств не существует.

Найдите решение своей проблемы в документации

Большая часть документации относительно сухая и предназначена для предоставления ответов, и ее не обязательно интересно читать. Гораздо проще сосредоточиться на нем, пока ищешь решение проблемы.

Я ненавижу читать документацию, чтобы узнать о проекте. Неважно, начинаю ли я новый проект или изучаю библиотеку. Это похоже на пустую трату времени, потому что у меня нет контекста, и мне трудно понять связь между вещами, о которых я читаю.

Вместо этого я пытался сделать что-то самостоятельно, терпел неудачу и возвращался к документации в поисках ответа. В этом случае я, по крайней мере, знаю то, чего не знаю, и стремлюсь заполнить пробелы.

Используйте инструменты поиска в документации

Вы можете использовать инструменты поиска, чтобы быстро получить нужную информацию, когда вам нужно решить проблему.

В случае сторонних библиотек вы можете использовать поисковые системы, чтобы ограничить поиск веб-сайтом проекта, добавив site:<domain>:

То же самое работает с Google, Bing и DuckDuckGo.

Для документации в коде вы можете использовать те же инструменты, которые вы используете для поиска в кодовой базе:

• поиск в редакторе

• рипгреп

• или git grep

Пример с git grep:

$ git grep 'http.post'

src/auto/injector.js: * $http.post(trackingUrl, trackedEvents);

src/ng/http.js: * $http.post('/someUrl', data, config).then(successCallback, errorCallback);

src/ng/http.js: * - {@link ng.$http#post $http.post}

Поиск по документу имеет несколько преимуществ:

• вы можете ознакомиться со структурой документации

• вы найдете все части документации, относящиеся к вашей теме

Справочник по API - сухое описание методов

Учебник или руководство — это дает больше контекста.

Не волнуйтесь, если вы не понимаете документацию

Качество документации сильно различается. Часто это не очень доступный документ. Возможно, есть предположение, что читатель обладает некоторыми системными знаниями, а в тексте это явно не указано. Это оставляет новичков немного потерянными.

Наиболее проблематичными могут быть коммерческие проекты с закрытым исходным кодом. Если у вас есть небольшая команда, поддерживающая как кодовую базу, так и ее документацию, могут пройти месяцы между тем, как любой новый взгляд просматривает документацию и пытается разобраться в ней.

Проекты с открытым исходным кодом обычно немного лучше. У тех, у кого нет хорошей документации, меньше шансов на успех.

Не пропускайте руководства

Если проект предоставляет учебник или руководство, неплохо было бы проверить его. Если вы часто сталкиваетесь с подобной проблемой, просто найдите часть руководства, посвященную этой проблеме, и просмотрите ее. Хорошо сделанное руководство предоставит вам контекст, необходимый для полного понимания механизма, который вы используете.

Глубокое погружение в соответствующие части API

Описание API — это самая техническая документация. Обычно он довольно сух, и ему не хватает хорошего обзора контекста, в котором вы можете использовать данный метод. Он показывает вам все классы, методы, аргументы и выходные данные, которые у вас есть.

Если возможно, просмотрите различные описания одних и тех же или похожих вещей. Часто один метод состоит в том, чтобы сослаться на какой-то другой, поэтому, если вы все еще теряетесь после прочтения о первом, вы можете проверить, делает ли документация других более понятным.

Полученные результаты

С помощью методов вы либо измените внутреннее состояние объекта, либо получите некоторый результат. Руководство по API должно довольно хорошо описывать и то, и другое.

Вариант ввода

Часто методы принимают входные данные во многих комбинациях аргументов. Документы покажут вам все варианты, чтобы получить все, что вам нужно.

Заключительные мысли о документации

Чтение документации — важный навык, и его можно освоить только на практике. Не расстраивайтесь, когда у вас возникают трудности с первыми попытками; со временем становится лучше.