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

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

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

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

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

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

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

Хороший дизайн макета также действительно поможет пользователям сканировать каждый раздел документации без напряжения глаз. Несколько хороших примеров (или мои любимые) - документация для Bootstrap и WordPress. “Первые шаги с WordPress”.

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

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

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

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

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

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

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

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

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

Есть несколько факторов, которые помогут создать хороший документ.

1. Никогда не предполагайте

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

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

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

2. Следуйте Стандарту

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

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

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

• PHP: Стандартная документация PHP для WordPress
• JavaScript: UseJSDoc
• CSS: CSSDoc

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

3. Графические элементы

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

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

4. Секционирование

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

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

5. Пересмотреть и обновить

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