Техническая документация по разработке ПО: типы, лучшие практики и инструменты

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

Что такое техническая документация при разработке ПО?

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

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

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

Этап проекта	Проектная документация	Функции
1. Этап планирования (заинтересованные стороны, пользователи, разработчики, UX-дизайнеры)	Требования высокого уровня и проектная документация Требования низкого уровня и проектная документация	Определение того, что представляет собой продукт, как он должен выглядеть и работать. Установка стандартов кодирования, шаблонов проектирования, руководств по стилю, пользовательских потоков и ментальных карт.
2. Этап обеспечения качества	Планы испытаний и стандарты. Тестовая документация	Формулирование стандартов тестирования, задач, потоков тестирования и типов тестов. Определение предмета тестирования. Документирование результатов тестирования.
3. Пользовательская документация	Системная документация Руководства для конечных пользователей Руководства по установке	Создание инструкций по обслуживанию, установке и использованию продукта.
4. Выпуск	Итоговые отчеты

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

Подходы Agile и Waterfall к документации ПО

Типы документации, которую создает команда, и ее объем зависят от выбранного подхода к разработке программного обеспечения. Основных два: Agile и Waterfall. Каждый из них уникален с точки зрения сопроводительной технической документации.

Waterfall — водопадный подход

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

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

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

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

По данным глобального опроса KPMG по Agile, проведенного в 2019 году, 81% компаний инициировали Agile-трансформацию за последние три года.

Agile — гибкий подход

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

Основными строительными блоками Agile-разработки являются итерации: каждая из них включает планирование, анализ, проектирование, разработку и тестирование.

Метод Agile на начальном этапе не требует подробной документации. Менеджерам не нужно планировать заранее, поскольку все может измениться по мере развития проекта. Это позволяет осуществлять планирование точно в срок.

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

Сегодня Agile является наиболее распространенной практикой разработки программного обеспечения, поэтому мы сосредоточимся на методах документирования, связанных с этим методом.

Виды технической документации

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

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

I. Документация продукта

1. Системная документация
   1. Документ с требованиями к продукту
   2. UX-проектная документация
   3. Документация по проектированию архитектуры ПО
   4. Документ с исходным кодом
   5. Документация по обеспечению качества
   6. Руководство по обслуживанию и помощи
   7. Документация по API
2. Пользовательская документация
   1. Документация для конечного пользователя
   2. Документация системного администратора

II. Технологическая документация

1. Гибкие дорожные карты продукта
2. Планы
3. Оценки
4. Расписания
5. Отчеты и показатели
6. Рабочие бумаги
7. Стандарты

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

Существует два основных типа документации на продукцию:

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

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

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

Продукт: Системная документация

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

Документ с требованиями к продукту

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

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

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

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

Цели команды и бизнес-задачи. Определите наиболее важные цели в краткой форме.

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

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

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

Критерии приемки. Это условия, указывающие на завершение пользовательской истории. Основная цель критериев приемки — определить удовлетворительный результат для сценария использования с точки зрения конечного пользователя.

Взаимодействие с пользователем и дизайн. Свяжите исследования дизайна и каркасы со страницей.

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

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

Сделайте всю эту информацию более полной, используя следующие методы:

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

Вы можете включить диаграммы в процесс создания требований, используя следующие программные инструменты для создания диаграмм: Visio, Gliffy, Balsamiq, Axure или SmartArt в Microsoft Office.

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

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

Стадия исследования включает в себя:

• Профили пользователей
• Пользовательский сценарий
• Карта сценария
• Карта пользовательских историй
• Руководство по UX-стилю

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

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

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

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

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

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

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

Наиболее распространенными документами, создаваемыми на этих этапах, являются:

• Карты сайта
• Каркасы
• Макеты
• Прототипы
• Схемы потока пользователя или путь пользователя
• Отчеты о тестировании юзабилити

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

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

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

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

Прототип — это макет, с которым можно взаимодействовать: нажимать кнопки, перемещаться между разными страницами и так далее. Прототип можно создать в инструменте прототипирования, таком как Sketch или MockFlow. Используя шаблоны, UX-дизайнеры могут создавать интерактивные макеты на ранних этапах разработки, которые будут использоваться для тестирования юзабилити.

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

Документ проекта архитектуры программного обеспечения

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

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

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

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

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

Эффективный документ по проектированию и архитектуре включает следующие информационные разделы.

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

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

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

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

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

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

Документ с исходным кодом

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

Документы с исходным кодом могут включать, помимо прочего, следующие сведения:

• Фреймворк генерации HTML и другие применяемые фреймворки;
• Тип привязки данных;
• Шаблон проектирования с примерами (например, модель-представление-контроллер);
• Меры безопасности; и
• Другие закономерности и принципы.

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

Документация по обеспечению качества

В Agile существуют разные типы пользовательского приемочного тестирования . Мы выделили наиболее распространенные:

• План управления качеством
• Стратегия тестирования
• План испытаний
• Спецификации тестового примера
• Тестовые контрольные списки

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

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

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

Этот документ должен содержать:

• Список функций, которые будут протестированы
• Методы тестирования
• Сроки
• Роли и обязанности (например, модульные тесты могут выполняться либо командой контроля качества, либо разработчиками программного обеспечения)

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

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

Контрольный список тестов — это список тестов, которые следует запустить в определенное время. Он показывает, какие тесты завершены и сколько провалились. Все пункты в контрольных списках испытаний должны быть определены правильно. Попробуйте сгруппировать контрольные точки в чек-листах. Такой подход поможет вам отслеживать их во время работы и не потерять ни одного. Если это поможет тестировщикам правильно проверить приложение, вы можете добавить комментарии к своим пунктам в списке.

Руководство по обслуживанию и помощи

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

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

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

Документация по API

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

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

Продукт: Пользовательская документация

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

• конечные пользователи
• системные администраторы

Документация для конечного пользователя

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

Ниже приведены основные типы пользовательских документов.

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

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

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

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

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

• Часто задаваемые вопросы
• Видеоуроки
• Встроенная помощь
• Порталы поддержки

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

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

Система Wiki — одна из наиболее полезных практик. Это помогает поддерживать существующую документацию. Если вы используете вики-систему, вам не нужно будет экспортировать документы в презентабельные форматы и загружать их на серверы. Вы можете создавать свои вики-страницы, используя язык разметки вики и HTML-код.

Документация системного администратора

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

• Функциональное описание – описывает функциональные возможности продукта. Большая часть этого документа подготовлена ​​после консультации с пользователем или владельцем.
• Руководство системного администратора — объясняет различные типы поведения системы в разных средах и с другими системами. Он также должен содержать инструкции о том, как действовать в ситуациях неисправности.

Технологическая документация

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

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

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

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

Стандарты. Раздел о стандартах должен включать все стандарты кодирования и UX, которых команда придерживается на протяжении всего проекта.

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

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

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

Agile-команды по продуктам используют три типа дорожных карт продукта:

• Стратегическая дорожная карта
• Технологический или ИТ-дорожный план
• План выпуска

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

Темы — это несколько задач, которые должна выполнить команда и которые каким-то образом связаны между собой. Например, тема может звучать как «увеличить скорость загрузки страниц», что влечет за собой несколько действий. Группировка информации по темам делает дорожную карту очень гибкой и обновляемой, что отлично подходит для разработки на основе спринтов.

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

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

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

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

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

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

Инструменты общего назначения

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

• Atlassian Confluence — самый популярный инструмент для совместной работы над проектами, обладающий целой экосистемой для управления требованиями к продукту и написания документации. Confluence известен стабильной вики-системой и эффективным интерфейсом управления пользовательскими историями.
• Document 360 — это база знаний/платформа документации для самообслуживания, предназначенная для продуктов «программное обеспечение как услуга».
• bit.ai — это инструмент для совместного создания, хранения, обмена данными и использования вики-системы документации. Документация является интерактивной, что означает, что разработчики могут вставлять блоки или фрагменты кода прямо в документ и делиться им одним щелчком мыши. Закончив редактирование документации, вы можете сохранить ее в формате PDF или в формате уценки и опубликовать на любой другой платформе.
• Github не нуждается в представлении, за исключением тех, кто хочет использовать его для документации программного обеспечения. Он предоставляет вам собственную вики-систему и позволяет конвертировать вашу документацию в убедительные витрины веб-сайтов.

Редакторы Markdown

Поскольку документацию по программному обеспечению легче использовать в Интернете, ее необходимо создавать в правильном формате. Вот почему используются текстовые языки разметки. Самым популярным из них является Markdown, который легко конвертируется в HTML и не требует каких-либо специальных знаний для его использования. Разметка используется на GitHub и Reddit и практически везде для веб-документации.

Итак, вот несколько редакторов Markdown, которые могут быть полезны для создания документов для вашего проекта:

• Visual Studio Code — это бесплатный редактор кода с открытым исходным кодом, разработанный Microsoft для Windows, Linux и macOS. Он имеет множество функций и расширений, в том числе для управления проектами и совместной работы.
• Typora — это редактор, который обеспечивает среду написания, не отвлекающую от внимания, и рендеринг синтаксиса уценки в реальном времени для легкого создания и редактирования файлов Markdown.
• iA Writer — минималистичный текстовый редактор, предназначенный для письма. Он предоставляет простой, не отвлекающий от внимания интерфейс с рядом полезных функций, включая подсветку синтаксиса, подсчет слов и синхронизацию с iCloud.
• Quiver — это приложение для создания заметок и управления фрагментами кода для устройств Mac и iOS. Он позволяет пользователям создавать и систематизировать заметки, используя комбинацию текста, фрагментов кода и Markdown.

Специальные инструменты дорожной карты

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

• ProductPlan — это облачное программное обеспечение для создания дорожных карт продуктов, которое предоставляет функции для составления дорожных карт, создания графиков, совместной работы, определения приоритетов и отчетности, чтобы помочь компаниям разрабатывать, делиться и управлять своими дорожными картами продуктов более эффективным и действенным способом.
• Aha! — это программное обеспечение для создания дорожной карты продукта, которое предоставляет набор инструментов для управления всем жизненным циклом управления продуктом, от идеи до запуска.
• Roadmunk — это веб-инструмент, который предлагает такие функции, как настраиваемые поля, редактирование перетаскиванием, интеграцию с другими инструментами и функции совместной работы, позволяющие членам команды работать вместе в режиме реального времени.
• Roadmap Planner — еще один инструмент визуального планирования проектов и совместной работы в команде, используемый для создания дорожных карт проектов, сроков и диаграмм Ганта.

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

Инструменты для UX-документации

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

• Sketch — это простой, но мощный инструмент векторного дизайна, имеющий веб-приложение и клиент для настольных компьютеров Mac. Sketch хорошо известен и достаточно прост, предлагая достаточно возможностей для проектирования интерфейсов.
• InVision — один из самых популярных инструментов для прототипирования. InVision известен своими функциями совместной работы и кроссплатформенностью, что делает его отличным инструментом для проектирования будущих интерфейсов.
• UXPin — это инструмент проектирования для Mac и Windows, который позволяет создавать чертежи любого типа. Вы также можете загрузить свои эскизы или каркасы из других продуктов и создать их интерактивный прототип.
• Adobe XD , где XD означает «дизайн опыта», — это продукт, предназначенный для специалистов по UX. Продукт ориентирован на UX-специалистов. Оно позволяет дизайнерам создавать высококачественные прототипы и делиться ими через приложение.

Инструменты для документации API

Процесс создания документации API чаще всего автоматизирован. Программисты или технические писатели могут использовать генераторы документации API, такие как:

• Swagger — это бесплатная само-документируемая программная служба, предназначенная для создания и обновления веб-служб и API RESTful.
• RAML 2 HTML — это простой генератор документации, использующий спецификации RAML.

Инструменты для технических писателей

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

Некоторые популярные CMS включают в себя:

• MadCapFlare — мощное облачное программное обеспечение с функцией многоканальной публикации, многоязычной поддержкой, обширными учебными ресурсами и многим другим.
• Adobe RoboHelp — полнофункциональная CMS, позволяющая создавать мультимедийный контент, удобное управление микроконтентом, совместную работу по контролю версий и т. д.
• ClickHelp — отмеченная наградами платформа, предлагающая простой переход из других программ, гибкие параметры разрешений и ряд возможностей отчетности.

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

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

Общие шаблоны проектной документации

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

• Atlassian Confluence Templates предлагает готовые к использованию шаблоны проектной документации общего назначения.
• Ready SET Pro — это большая библиотека шаблонов документации по программному обеспечению в формате HTML, которая включает документы планирования, архитектуры, дизайна, требований, тестирования и многое другое.
• ReadTheDocs — это универсальный шаблон, созданный на платформе ReadTheDocs, содержащий инструкции по написанию каждого типа документов, которые могут вам понадобиться, от архитектурных и UML-диаграмм до руководств пользователя.

Шаблоны дорожных карт продукта

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

• Office-time-line
• Шаблон.net
• Шаблон-лаб
• Usefyi

Образцы документации по обеспечению качества

Если вы все еще ищете шаблоны, связанные с контролем качества, вы можете проверить здесь:

• StrongQA.com предлагает различные шаблоны документации для специалистов по контролю качества. К ним относятся контрольные списки тестирования, шаблоны тестирования, планы тестирования и многое другое.
• На сайте Template.net есть раздел с шаблонами планов обеспечения качества.
• EasyQA предлагает SDK для тестирования программного обеспечения и шаблоны с подробными инструкциями по созданию плана качественного тестирования.
• Тестирование ПО — это большая платформа, включающая в себя блог, форум и всевозможные информационные материалы для специалистов по тестированию.

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

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

• Примеры шаблонов
• К вашему сведению
• CX работает
• cs.iit.edu
• CMS
• cs.dal.ca

Примеры специализированной архитектуры: AWS, Microsoft Azure и Google Cloud

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

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

Как писать документацию по программному обеспечению: общие советы

Существует несколько общих практик, которые можно применить ко всем основным типам документации, которые мы обсуждали выше.

Напишите достаточно документации

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

Учитывайте свою аудиторию

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

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

Используйте перекрестные ссылки

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

Не игнорируйте глоссарии

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

Поддерживайте актуальность документации

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

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

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

Документация — это совместная работа всех членов команды

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

Наймите технического писателя

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

Лучшие практики создания и ведения технической документации

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

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

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

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

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

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

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

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

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

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

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

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

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