Что такое программная документация? Типы и рекомендации для начала работы

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

Но что такое программная документация на самом деле и как вы можете создать ее для своего проекта?

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

• Что такое программная документация?
• Различные типы документации по программному обеспечению (с примерами)
• Как опубликовать документацию по программному обеспечению (лучшие инструменты)
• Некоторые рекомендации по созданию качественной документации по программному обеспечению

Давайте копать!

Что такое программная документация?

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

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

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

Различные типы документации по программному обеспечению

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

Первое соображение заключается в том, для какого типа лиц предназначена документация:

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

Второе соображение заключается в том, предназначена ли документация для внешней или внутренней аудитории:

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

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

Давайте разберем эти типы документации по программному обеспечению немного подробнее…

Примеры документации программного обеспечения для документации разработчика

• Документация по API — покажите разработчикам, как взаимодействовать с API вашего программного обеспечения.
• Readme — представьте свое программное обеспечение и объясните, что оно делает — обычно это первое, что люди читают.
• Примечания к выпуску — документируйте новые выпуски вашего программного обеспечения, включая любые важные изменения.
• Документация по архитектуре — покажите структуру вашего программного обеспечения, возможно включая диаграммы.
• Документация модели данных — задокументируйте различные структуры данных в вашем программном обеспечении, включая отношения между различными структурами данных.
• Документация по процессам — документируйте ключевые процессы, такие как отчеты об ошибках, дорожные карты, обеспечение качества, протоколы тестирования и т. д.

Для реального примера документации программного обеспечения, ориентированной на разработчиков, вы можете посмотреть документацию Gravity Forms «Для разработчиков», которая охватывает различные темы, такие как:

• PHP-хуки (для WordPress)
• Объекты данных
• PHP-API
• База данных
• ОТДЫХА API

Например, вот как выглядит документация REST API:

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

• Руководство по началу работы — покажите пользователям, как быстро приступить к работе с вашим программным обеспечением.
• Учебники для конкретных случаев использования — более конкретные учебные пособия для выполнения определенных задач.
• Глоссарии терминов/справочники – помогают пользователям понять ключевые термины и детали.
• Часто задаваемые вопросы — ответы на часто задаваемые вопросы.

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

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

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

Как публиковать документацию по программному обеспечению: три лучших инструмента для документирования программного обеспечения

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

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

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

Героическая база знаний

Heroic Knowledge Base — это плагин документации и базы знаний для популярного программного обеспечения WordPress с открытым исходным кодом.

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

Вот некоторые из основных функций, которые вы получаете с Heroic Knowledge Base:

• Гибкий редактор контента , включая встроенные блоки для выносок и других важных деталей стиля.
• Автоматическое оглавление , чтобы пользователи могли быстро увидеть, какой контент рассматривается в статье документации, и перейти к определенным разделам.
• Контроль версий и история версий через встроенную систему редакций WordPress.
• Функции обнаружения контента , включая поиск Ajax в реальном времени с интерактивными предложениями, категориями и многим другим.
• Система обратной связи с пользователями , которая позволяет людям оценивать статьи как полезные или бесполезные и делиться отзывами.
• Аналитика поиска , чтобы вы могли видеть, что ищут пользователи, а также любые условия поиска, которые не дают результатов.
• Виджет «Мгновенные ответы» , позволяющий пользователям искать и получать доступ к документации по программному обеспечению из любого места на вашем сайте.

Поскольку база знаний Heroic и WordPress размещаются самостоятельно и имеют открытый исходный код, вы также можете свободно изменять свои настройки по мере необходимости.

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

База знаний Heroic стоит всего 149 долларов в год.

Читать документы

Read the Docs — это инструмент документации, предназначенный для помощи в создании документации для разработчиков.

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

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

Вот некоторые из других примечательных особенностей Read the Docs:

• Встроенная аналитика, чтобы увидеть, что ваши пользователи читают и ищут.
• Поддерживает несколько одновременных сборок , что может быть полезно, если вы предлагаете несколько версий своего программного обеспечения — например, один набор документации для версии 1.0, а другой — для версии 2.0.
• Экспорт документации в различных форматах, включая PDF, HTML и epub.
• Интерактивные поисковые подсказки, помогающие пользователям находить документы.

Read the Docs можно использовать бесплатно, если у вас есть проект программного обеспечения с открытым исходным кодом.

Для коммерческих программных продуктов существует платная услуга Read the Docs for Business, стоимость которой начинается от 50 долларов в месяц.

Гитбук

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

Или, если вы не хотите использовать Git, GitBook также позволяет создавать документацию с помощью текстового редактора или импортировать ее из файлов markdown или .doc.

Вот некоторые другие примечательные функции, которые предлагает GitBook:

• Контроль версий для отслеживания изменений и истории версий.
• Групповое редактирование в реальном времени , которое полезно, если вам нужно, чтобы несколько авторов совместно работали над статьями.
• Организуйте статьи , используя «пространства» и «коллекции» — в каждом пространстве может быть несколько коллекций.
• Опция экспорта PDF , чтобы пользователи могли легко экспортировать вашу документацию в формате PDF.

GitBook бесплатен для некоммерческих организаций или проектов с открытым исходным кодом.

Для коммерческих программных проектов GitBook стоит от 8 долларов за пользователя в месяц при минимальном количестве пользователей 5. Это означает, что самая дешевая месячная ставка составляет 40 долларов в месяц.

Лучшие практики создания документации к программному обеспечению

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

Подумайте о целях и потребностях пользователей

Когда вы пишете статью о документации по программному обеспечению, важно начать с ответов на несколько основных вопросов:

• Кто тот пользователь, для которого вы пишете?
• Чего пытается добиться пользователь?
• Какой уровень технических знаний у пользователя?

Знание ответов на эти вопросы поможет вам понять, какой контент освещать и как наиболее оптимально структурировать статью.

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

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

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

Включите документацию по программному обеспечению в процесс разработки

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

Однако это может быстро привести к задолженности по документации, поскольку вы можете выпускать новые функции или изменения до того, как они будут задокументированы.

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

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

Используйте согласованное форматирование и стиль

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

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

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

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

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

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

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

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

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

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

Сделайте так, чтобы людям было легко находить контент (поиск/фильтр)

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

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

Одна из первых стратегий — разделить вашу документацию по типам.

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

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

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

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

Многие инструменты документации включают встроенную функцию поиска в реальном времени, включая базу знаний Heroic.

Обновляйте документацию по программному обеспечению

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

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

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

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

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

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

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

Чтобы автоматизировать процесс обратной связи с клиентами, вам понадобится инструмент управления документацией, который включает встроенные функции для обратной связи с клиентами.

Например, плагин Heroic Knowledge Base позволяет пользователям оценивать статью как полезную или бесполезную, а также при желании оставлять отзывы в свободной форме.

Затем вы можете просматривать всю эту информацию на панели управления, чтобы быстро находить статьи документации, которые необходимо улучшить.

Начните документировать свое программное обеспечение сегодня

Документация по программному обеспечению помогает вам и вашим клиентам работать более эффективно и получать больше пользы от вашего программного обеспечения.

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

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

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

Чтобы опубликовать эту документацию, вы можете использовать инструмент с открытым исходным кодом, такой как Heroic Knowledge Base, который основан на мощном программном обеспечении WordPress.

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

Если вы хотите узнать больше, нажмите здесь, чтобы перейти в базу знаний Heroic.