Как сделать документацию более удобной для чтения
project-management beginners learning project-planning api-documentation documentation software-documentation project-documentation

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

13 апреля 2022 г.

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


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


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


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


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


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


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


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


Намного проще сосредоточиться на документации при поиске решения проблемы


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


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


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


вы можете использовать поисковые системы, чтобы ограничить поиск сайтом проекта, добавив 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 является самой технической документацией


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


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


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


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


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


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


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


Оригинал

Recent Post

Categories

PREVIOUS ARTICLE
NEXT ARTICLE