Разработчики: почему не стоит пропускать документацию

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

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

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

Рекомендуемое чтение: обучение программированию: 10 заблуждений, которые не соответствуют действительности

Хорошая документация помогает пользователям

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

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

Хороший дизайн макета также действительно поможет пользователям просматривать каждый раздел документации без утомления глаз. Несколько хороших примеров (или мои любимые) – это документация для начальная загрузка а также WordPressFirst «Первые шаги с WordPress».

Это помогает другим разработчикам

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

Но в отличие от документации конечного пользователя, эта документация обычно описывает технические процедуры, такие как соглашение о присвоении имен кодам, показывая, как должны создаваться конкретные страницы, и как работает API вместе с примерами кода. Часто нам также приходится писать документацию, встроенную в код (известный как Комментарии) описать, что делает код.

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

Читайте также: 10 разработчиков привычек программирования должны принять

Странно, это также помогает кодеру

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

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

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

Что делает для хорошей документации?

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

Например, если вы создали плагин jQuery, вы можете черпать вдохновение из SlickJSДокументация. Он показывает, как структурировать HTML, куда поместить CSS и JavaScript, как инициализировать плагин jQuery на его самом базовом уровне, и даже показывает полную окончательную разметку после добавления всех этих вещей, что является очевидным.

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

/ **
* Добавляет пользовательские классы в массив классов тела.
*
* @param array $ classes Классы для элемента body.
* @return array
* /
function body_classes ($ classes) {
// Добавляет класс group-blog в блоги с более чем 1 опубликованным автором.
if (is_multi_author ()) {
$ классов[] = ‘группа-блог’;
}

вернуть $ классы;
}
add_filter (‘body_class’, ‘body_classes’);

Ниже приведено несколько справочных материалов по форматированию встроенной документации с лучшими практиками в PHP, JavaScript и CSS:

Если вы используете SublimeText, я бы предложил установить DocBlockr это умно предварительно заполнит ваш код встроенной документацией.

Читайте также: Стандарты кодирования для WordPress [Guide]

1. Графические элементы
   Используйте графические элементы, они говорят лучше, чем текст. Эти медиа полезны, особенно если вы создаете программное обеспечение с графическим интерфейсом. Вы можете добавить указывающие элементы, такие как стрелки, кружки или что-нибудь, что может помочь пользователям понять, куда идти, чтобы выполнить шаги, без догадок.

Ниже приведен пример приложения Tower, из которого вы можете черпать вдохновение. Они эффективно объясняют, как работает управление версиями, приятным способом, который делает его более понятным, чем использование командных строк в виде простого текста.

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

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

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