У команд разработчиков продуктов и программного обеспечения есть общая беда: документация.
Документация продукта относится к руководствам и руководствам для пользователей, которые объясняют рабочий процесс и пользовательский интерфейс продукта. Как обычный пользователь может продуктивно работать с этим продуктом? В этом смысле документация по продукту может быть использована для программных продуктов.
Документация по программному обеспечению относится к базовым технологиям, предпосылкам и настраиваемым атрибутам программного продукта. Как ИТ-администраторы настраивают, контролируют, размещают и развертывают программный продукт для пользователей? Этот тип документации очень важен, особенно когда добавляется несколько версий или ответвлений.
В некотором смысле, документация по продукту - это как обучение вождению автомобиля. Руль поворачивает машину, педаль газа двигает машину, педаль тормоза останавливает машину. Документация по программному обеспечению учит человека тому, как работает автомобиль. Колесо связано с передней осью, которая поворачивает передние шины, изменяя курс движения; педаль газа увеличивает поток воздуха в двигатель, который всасывает больше топлива, создавая крутящий момент и мощность.
Оба вида документации важны. Один обучает пользователей, а другой - администраторов и разработчиков. Хорошо показывать людям, как водить машину, но если никто не знает, как она работает, что произойдет, когда машина сломается?
Небольшие различия между документацией по продуктам и программному обеспечению
Существуют незначительные различия, о которых следует знать при работе с документацией по продуктам и программному обеспечению:
Документация по программному обеспечению и документация по продукту: Целевая аудитория и персоны
Документация по продуктам рассчитана на одну аудиторию - пользователей. Она предполагает, что пользователь не обладает техническими знаниями, и общается на простом английском языке с минимальным количеством жаргона. Подобно техническому образованию в сравнении с университетской степенью, она обучает людей тому, как делать вещи, уделяя меньше внимания теоретическим или концептуальным знаниям.
Документация по программному обеспечению предназначена для ИТ-администраторов, инженеров и разработчиков. Она охватывает дизайн и архитектуру программного обеспечения, инструкции по настройке командной строки, поддержку API и интеграции, управление данными и отчетность, топологию сети - в общем, все, что заставляет машину работать. Эти документы образуют единый источник истины (SSOT), к которому ИТ-персонал может обращаться при мониторинге и устранении неполадок программного приложения.
Документация по программному обеспечению и продуктам: Частота обновления
Документация по программному обеспечению должна постоянно обновляться по мере слияния новых коммитов в основной канал релиза. Документация по программному обеспечению должна подчеркивать новые функции и команды и обесценивать старые возможности. Новые или изменяющиеся зависимости должны быть задокументированы, а поддержка функций на всех целевых платформах должна быть уточнена - например, одна функция работает на Windows, но не на Linux.
Документация по продукту нуждается в обновлении только тогда, когда базовые изменения в программном обеспечении вызывают изменения в рабочем процессе или удобстве использования. Разработчик меняет код платежного шлюза, но процесс оплаты для пользователей остается прежним, поэтому обновлений не требуется.
Это показывает естественную иерархию документации по программным продуктам. Техническая документация программного обеспечения формирует фундамент, а последующая документация продукта основывается на этом фундаменте. Поэтому основное внимание следует уделять созданию отличной документации по программному обеспечению, поскольку она порождает еще более отличную документацию по продуктам.
Примеры рамок форматирования для документации по продуктам и программному обеспечению
Часть документации по продукту может следовать этой схеме:
-
- Название продукта
-
- Обзор назначения продукта
-
Руководство по настройке
-
- Пояснения и изображения первой функции
-
- Пояснения и изображения функции 2
-
- Ссылки на поддержку клиентов
Аналогичным образом, часть документации по программному обеспечению может следовать этой схеме:
-
- Название программного обеспечения
-
- Обзор назначения программного обеспечения
-
- Зависимости программного обеспечения
-
Руководство по установке
-
- Пояснения и изображения функции 1
-
- Пояснение функции 2 и изображения
-
Ссылки на техническую поддержку
Очевидно, что эти два типа документации тесно связаны друг с другом и имеют схожую структуру. Это означает, что командам разработчиков продуктов и программного обеспечения есть чему поучиться друг у друга, а также большой потенциал при совместной работе над документацией.
Команды разработчиков документации по продуктам и программному обеспечению могут дополнять друг друга
Существует значительное сходство между документацией по продуктам и программному обеспечению. В связи с этим возникает вопрос: могут ли команды разработчиков продуктов и программного обеспечения работать вместе?
Да, могут, и должны!
Команды разработчиков программного обеспечения понимают технический жаргон и лежащие в основе технологии. Команды разработчиков продуктов понимают, что видят, хотят и нуждаются пользователи; пользовательский опыт. Составители документации для программного обеспечения могут предоставить подробную техническую информацию, а составители документации для продукта могут разбавить технические детали для потребления неспециалистами.
Представьте себе, что вы пытаетесь объяснить что-то в терминах непрофессионалов, не имея высокоуровневого понимания, необходимого для того, чтобы сформулировать что-то, понятное непрофессионалу. Вот что происходит, когда документация на продукцию создается раньше, чем документация на программное обеспечение.
Что такое квантовая механика? Кот Шредингера - это, вероятно, первая мысль в вашей голове! Но какое отношение квантовая механика имеет к кошкам? Для пользователя это неважно. Для физика это значит все.
Начните с документации программного обеспечения, закончите лучшей документацией продукта в Docsie
В заключение следует отметить, что использование документации по программному обеспечению в качестве шаблона для последующей документации по продукту имеет множество преимуществ. Программная документация должна выступать в качестве единого источника истины для ИТ-персонала и составителей документации на продукцию. После ее написания составители документации по продуктам получат ясность и понимание, чтобы упростить и поделиться с клиентами знаниями, удобными для пользователя, с техническим руководством для корректуры и проверки качества.
Проще говоря, начав с отличной документации по программному обеспечению, ваши писатели смогут создать еще более качественную документацию по продуктам!
Начните создавать документацию, которая поможет вашим клиентам делать больше. Подпишитесь на наш стартовый план (forever free!) и создавайте документацию с Docsie!