Как разработчик, ваша гордость и радость — ваш код. Он читабелен, соответствует принципам СУХОЙ, отражает лучшие практики, а конечный продукт является отличным инструментом, который решает какую-то проблему для своих целевых пользователей. Однако, независимо от того, сколько работы вы вложили в свой код, если ваше программное обеспечение не содержит документации, или вы пишете документацию как запоздалую мысль и относитесь к ней с малой важностью, пользователи, скорее всего, получат мало удовольствия от работы с ней, и в конечном итоге выбрать другой, более удобный для пользователя продукт.
В этой статье вы найдете несколько практических руководящих принципов, которые помогут вам приступить к написанию первой документации по программному обеспечению.
Почему документация важна
Что касается вашего программного обеспечения, у Майка Поупа есть подходящее высказывание, которое звучит так: если оно не задокументировано, его не существует .
Почему это? Ну, просто чтобы взять мой личный опыт в качестве примера, я просматривал Интернет в поисках новых библиотек анимации JavaScript, чтобы попробовать и наткнулся на одну с описанием ее функций, которые мне действительно понравились. Тем не менее, не было никакой документации, даже раздела «Начало работы», а была просто API-страница, почти без объяснений или примеров. Как вы думаете, я использовал эту библиотеку? Конечно нет. Я был настолько разочарован этим, что перешел к чему-то, что имело для меня больше смысла.
На вопрос о том, почему хорошие библиотеки JavaScript терпят неудачу , Николас Закас дает следующий ответ :
Отсутствие документации . Неважно, насколько прекрасна ваша библиотека и насколько разумен ее дизайн, если вы единственный, кто ее понимает, она не принесет пользы. Документация означает не только автоматически сгенерированные ссылки на API, но также аннотированные примеры и подробные учебные пособия. Вам нужно все три, чтобы убедиться, что ваша библиотека может быть легко принята.
Другая важная причина, по которой ваши документы по программному обеспечению имеют решающее значение, заключается в том, что они служат средством связи между вашим нынешним «я» и вашим будущим «я», а также между вашим нынешним «я» и другими разработчиками, которые в конечном итоге могут оказаться работающими над вашим программным обеспечением. Даже если вы пишете читаемый и прокомментированный код, это не обязательно означает, что через шесть месяцев вам все равно будет понятно, почему вы написали функцию или любой другой фрагмент вашего кода в этом отношении, как вы это сделали.
Документация позволяет перенести код « почему» . Аналогичным образом комментарии к коду объясняют, почему , а не как документация служит одной и той же цели. — Руководство для начинающих по написанию документации
Конечно, вы хотите, чтобы люди использовали ваш код, а также смогли в конечном итоге обновить его и улучшить его. Все эти факторы способствуют росту поддерживающего сообщества, стоящего за вашим продуктом, что важно для его устойчивости, зрелости и успеха.
Будет очень трудно выполнить все это, если ваше программное обеспечение не имеет больших документов, чтобы пойти с ним.
Для кого предназначена документация по программному обеспечению
Когда вы пишете что-либо, убедитесь, что вам ясно, кто ваша аудитория. Документы не являются исключением из этого правила. Это прояснит в вашей голове проблемы, с которыми вероятно столкнется ваша аудитория, знакомство с вашим продуктом или предпосылки для использования вашего продукта. Эта информация имеет решающее значение для того, как вы создаете контент и язык, который вы используете.
Эта статья не касается двух видов документации:
- Руководства пользователя Например, моя сестра может решить использовать WordPress для публикации своего блога. Она не разработчик, но она слышала, что не-разработчики могут быстро запустить и запустить свой блог с помощью WordPress. Теперь ей понадобятся инструкции о том, как загрузить и настроить программное обеспечение на своем сервере, как писать, публиковать и обновлять свои сообщения, как добавлять изображения в сообщение и т. Д. Другими словами, ей понадобится пользователь руководство.
- Проектная документация. Этот вид документации больше связан с проектом, чем с самим программным обеспечением, хотя часть его содержимого может быть помещена в файл Readme проекта. Чтобы продолжить с примером WordPress, после много практики с WordPress, я мог бы решить, я хотел бы добавить функцию в программное обеспечение или исправить ошибку или два. В этом случае мне нужно знать такие вещи, как журналы изменений, соглашения и передовые практики, правила участия, как участвовать в групповых обсуждениях, имеющих отношение к поставленной задаче, и т. Д.
Тип документации, о которой я здесь говорю, в основном предназначен для разработчиков, которые имеют разные уровни знакомства с вашим программным обеспечением и должны использовать его в своих проектах. Например, если я создаю тему WordPress, мне нужно знать, с чего начать, как включить таблицы стилей и документы JavaScript, как связаться с базой данных для отображения сообщений и т. Д.
Что включить в вашу документацию
Популярным подходом является Readme Driven Development , отстаиваемый Томом Престоном-Вернером. Он состоит из написания документа Readme еще до того, как вы начнете писать какой-либо код. Этот документ представляет собой введение в ваше программное обеспечение и обычно включает в себя:
- объяснение того, что делает ваше программное обеспечение и какую проблему оно решает
- пример, иллюстрирующий обстоятельства, при которых ваш код обычно используется
- ссылки на код и трекер ошибок
- Часто задаваемые вопросы и способы обратиться за поддержкой
- инструкции по установке вашего программного обеспечения
- информация о лицензии
Однако, на мой взгляд, наличие надежной документации, которая действительно может помочь разработчикам, использующим ваше программное обеспечение / библиотеку, должно выходить далеко за рамки классического файла Readme. После Даниэле Прочида я предлагаю вам включить следующие элементы в документацию для удобства пользователей.
Учебники
Новичок с удовольствием найдет учебник в ваших документах по программному обеспечению. Обучающие программы показывают пользователям, как завершить проект с использованием вашего программного обеспечения, чтобы они могли быстро понять, что они могут с ним сделать.
Учебные пособия — это уроки, которые помогают читателю пройти серию шагов для завершения какого-либо проекта. Они — то, что нужно вашему проекту, чтобы показать новичку, что они могут достичь чего-то с ним. — Даниэле Прочида
Руководства
Практические руководства помогают пользователям решать реальные задачи с использованием вашего программного обеспечения. Прочида сравнивает их с рецептами в том смысле, что они являются указаниями, которые вы даете пользователям, чтобы они могли успешно достичь определенной цели. В отличие от учебных пособий, предназначенных для начинающих, практические руководства предполагают, что пользователи уже обладают некоторыми базовыми знаниями о функциях, инструментах и о том, как выполнять простые задачи.
Справочные руководства
Справочные руководства представляют собой технические ссылки на код вашего программного обеспечения — функции, API и т. Д. — и предлагают базовое описание того, как использовать программное обеспечение. Например, вы найдете иллюстрацию того, как создать экземпляр конкретного класса, как вызвать конкретный метод и так далее.
Справочные руководства представляют собой технические описания оборудования и способов его эксплуатации. — Даниэле Прочида
Это часть документации, которую вы, вероятно, найдете в большинстве проектов. Разработчики, как правило, неплохо пишут, поскольку знают все о своем коде и о том, как его использовать.
объяснение
Объяснения — это глубокое погружение или обсуждение конкретной темы, которая, по вашему мнению, имеет отношение к более высокому уровню понимания вашего программного обеспечения. Что касается объяснений, Прочида отмечает, что —
Этот раздел документации редко создается в явном виде, и вместо этого фрагменты объяснения разбросаны среди других разделов. Иногда раздел существует, но имеет имя, такое как « Фон» или «Другие примечания», и на самом деле не соответствует этой функции.
Тема не определяется конкретной задачей, которую вы хотите достичь, например, руководством по использованию, или тем, что вы хотите, чтобы пользователь изучил, например, учебным пособием. Это не определяется частью машины, как справочный материал. Это определяется тем, что, по вашему мнению, является разумной областью, которую следует попытаться охватить за один раз, поэтому разделение тем для обсуждения иногда может быть немного произвольным.
На что нужно обратить внимание
Давайте рассмотрим несколько полезных советов о том, как сделать ваши документы удобными и актуальными.
Сделайте ваши документы доступными для обнаружения
Хорошая идея — приложить некоторые усилия, чтобы облегчить поиск документации по вашему программному обеспечению. Вы можете использовать некоторые методы SEO вместе с некоторыми маркетинговыми стратегиями, чтобы как можно больше пользователей могли овладеть ими.
Кроме того, то, что вы помещаете в свои документы, должно быть организовано в структуру, которая упрощает поиск конкретной информации. Стив Конвес рекомендует структурировать свои документы в виде единого связанного дерева: начиная с корневого узла, который должен быть расположен в очевидном месте, доступном для всех заинтересованных пользователей, ко всем остальным элементам можно легко получить доступ. Файл Readme проекта прекрасно работает как отличный корневой узел для всего дерева.
Кроме того, если вы получаете запросы о помощи от пользователей вашего программного обеспечения, вы можете написать ответы и сделать их доступными на легко доступной странице часто задаваемых вопросов. Это уменьшит время, которое вы тратите на помощь пользователям, но также даст вам более четкое представление о том, какая информация нужна пользователям чаще всего, чтобы вы могли сначала документировать их и держать на видном месте в ваших документах.
Убедитесь, что ваши документы обновлены и не содержат ошибок
Легко получить доступ к документации по вашему программному обеспечению — это здорово, но если пользователи узнают, что его содержимое устарело, или пример кода или инструкции приводят к ошибочным результатам, это, как минимум, расстраивает. Тем не менее, Стив Конвес предлагает вам держать ваши документы близко к коду — например, в системе контроля версий. Таким образом, когда разработчики обновят код, они заметят материал документации, что делает обновление документов более вероятным явлением.
Кроме того, чтобы свести к минимуму возникновение ошибок, тщательно протестируйте инструкции и примеры кода, которые вы предоставляете в своих документах.
Дополнительный совет и некоторые популярные примеры
Не останавливайтесь на документации. Сообщения в блоге отлично подходят для того, чтобы сделать ваше программное обеспечение и его функции известными широкой аудитории потенциальных пользователей. Используйте свой блог, чтобы предлагать разъяснения о том, что делает ваш продукт, предоставлять удобные учебные пособия, советы и рекомендации, пошаговые инструкции, объяснять обновления и т. Д. Вы можете включить свой блог в отдельный веб-сайт, посвященный вашему программному обеспечению — возможно, с форум — вокруг которого может собираться и расти сильное сообщество.
Отличный пример этой более широкой идеи документации, на мой взгляд, реализован GreenSock , широко успешной платформой анимации JS, которой я часто пользуюсь, не в последнюю очередь потому, что ее веб-сайт предоставляет простые в использовании и хорошо структурированные документы, супер полезный форум, сообщения в блоге, быстрые советы и многое другое.
React и Vue.js также можно считать отличными примерами. Как только вы получаете доступ к соответствующим веб-сайтам, домашняя страница в кратком слогане сообщает вам, для чего нужна каждая библиотека, а затем более подробно рассказывает, почему библиотека может считаться отличным выбором для вашего проекта. Оба веб-сайта позволяют начать работу с меньшими затратами, используя мягкие введения, иллюстративные фрагменты, короткие задания, которые могут выполнить новички, используя игровые площадки кода и т. Д. Как только пользователи приобретут некоторую уверенность в новом программном обеспечении, они могут легко найти более технические документы по API, а также страницы. подробности о том, как получить помощь, отображение информации об экосистеме, предложение новостей или раздел блогов и т. д.
Чтобы покинуть зону JS и перейти в область популярных библиотек пользовательского интерфейса с отличными веб-сайтами, я не могу оставить Bootstrap . На веб-сайте Bootstrap вы сразу найдете информацию о том, для чего нужна библиотека и как быстро начать работу, а также подробные и хорошо структурированные документы и блог, чтобы держать пользователей в курсе того, что нового.
Вывод
Написание хорошей документации имеет свои проблемы, но, безусловно, сто раз окупится, если вы подумаете, насколько проще будет вашим пользователям реализовать возможности вашего программного обеспечения. Это, в свою очередь, способствует популярности вашего программного обеспечения, что делает его привлекательным и, следовательно, открывает возможность для создания сообщества разработчиков, которые готовы тратить свое время на его глубокое изучение и способствовать его росту, стабильности и долгосрочному развитию. использование.