Почти каждый разработчик столкнулся с какой-то плохой документацией в свое время. Я даже не могу вспомнить, сколько раз мне приходилось разговаривать с недовольным сотрудником службы технической поддержки о проблеме, которую должно было быть легко найти. Две компании, с которыми я работал, даже перестали использовать хорошее программное обеспечение из-за плохой документации.
Проблема с документацией заключается в том, что большинство разработчиков действительно не хотят ее писать. Для тех из нас, кто работает в Интернете, нам было легко, потому что документация не была критичной для многих веб-проектов. Большинству моих клиентов не нужны инструкции о том, как перемещаться по их сайтам или использовать основные инструменты администратора, которые я предоставляю. Однако все изменилось.
Поскольку веб-сайты и веб-инструменты стали более продвинутыми, я обнаружил, что работаю над большим количеством проектов, требующих документации. Я написал документацию для внешних API и сервисов, инструкции для других разработчиков в моей команде и учебные пособия для конечных пользователей. Большинство моих ранних попыток были безуспешными, и я оказался недовольным техником поддержки. Чтобы этого не случилось с вами; Вот несколько идей, которые помогут сделать вашу документацию лучше и сэкономить ваше время в процессе.
Знай свою аудиторию
Как и любой другой проект, вам нужно знать, для кого вы пишете. Если вы пишете для технически подкованных конечных пользователей или других разработчиков, вы обычно можете вырезать определенное количество вводного контента. Кроме того, вы не хотите путать среднестатистических веб-пользователей с подробностями о том, как вы справляетесь со сложной обработкой данных или распределением памяти.
Если вы обнаружите, что у вас есть отдельные группы пользователей, не бойтесь писать несколько комплектов документации. Поначалу это может показаться пугающим, но во многих случаях написание более коротких и кратких документов для конкретных групп пользователей занимает меньше времени, чем попытка порадовать всех одним. Хорошим примером являются поставщики CMS, большинство из которых предоставляют отдельную документацию для разработчиков, ИТ-администраторов и конечных пользователей.
Используйте автоматизированные инструменты
Большинство языков имеют системы для автоматизации документирования в некоторой степени. Обычно эти системы не создают ничего хорошего для конечных пользователей, но документация обычно направлена на других разработчиков. На большинстве языков инструменты генерируют документацию на основе комментариев в вашем коде. Интеграция их — это всего лишь вопрос изменения стиля комментирования в соответствии с ожиданиями генератора документации. Я на самом деле обнаружил, что это дало мне дополнительное преимущество, позволяя мне писать более последовательные комментарии.
Сделать документацию усилием сообщества
Некоторые из наиболее полезных ссылок для программирования включают группу людей. Полностью управляемая пользователем система, такая как вики, или система документации, такая как библиотека MSDN, которая позволяет пользователям прикреплять контент к существующей статье, может как повысить эффективность документации, так и уменьшить объем усилий, необходимых для ее обслуживания. Вики также являются отличным инструментом для внутреннего использования при подготовке документации. Во время разработки легко добавить быстрые заметки в вики, а затем скомпилировать содержимое в документацию во время выпуска. Даже если это система, которую могут редактировать только сотрудники, она предоставляет центральную справочную информацию для обходных путей, ошибок и распространенных ошибок.
Оставьте время для написания документации
Большинство бедствий, которые я видел, являются результатом спешки в процессе. Трудно сократить функцию или отодвинуть крайний срок, чтобы найти время для документации, но оно того стоит. Независимо от того, закончите ли вы кошмаром технической поддержки или потратите недели на то, чтобы ускорить работу новых разработчиков, вы пожалеете, что не потратили время на то, чтобы записать что-то.
По мере того, как веб-приложения становятся все более сложными, а веб-службы и API-интерфейсы становятся все более распространенными, написание документации становится все более важным для разработчиков. Надеемся, что эти указатели помогут вам стать более эффективным и эффективным автором документации.