4 основных типа документации, которые необходимы каждому продакт-менеджеру

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

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

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

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

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

В чем разница между обучающими материалами, руководствами, объяснениями и справочниками?¶

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

Обучающие материалы: Это информационная документация, ориентированная на обучение.

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

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

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

Причины создания качественной документации¶

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

Рассмотрим основные причины для создания эффективной документации.

Она помогает создать лучший процесс адаптации для ваших клиентов¶

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

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

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

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

Сокращение числа обращений в службу поддержки¶

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

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

Она помогает поддерживать вашу команду¶

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

Пошаговая инструкция по написанию эффективной документации¶

Написание содержания документа и организация этого процесса — совершенно разные задачи от выбора тона и обеспечения понятности документации. Как отмечает O'Reilly, существует 8 правил хорошей документации:

1. Создавайте документацию, привлекательную для читателя.

2. Создавайте полную документацию, охватывающую все аспекты проекта.

3. Пишите материал, который легко просматривать и понимать.

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

5. Пишите документацию с необходимыми повторениями.

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

7. Делайте документацию, в которую легко вносить вклад.

8. Создавайте документацию, которую легко найти и понять.

Эти элементы в основном касаются содержания. Далее рассмотрим, как структурировать информацию в шесть шагов:

Определите, что нужно документировать¶

Перед началом работы подумайте, какой тип документации вы создаете: обучающий материал, справочник, руководство или объяснение?

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

Создайте структуру¶

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

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

Всегда используйте качественные мультимедийные технологии¶

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

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

Обеспечьте возможность поиска¶

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

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

Docsie предлагает динамически настраиваемую навигацию с поиском для легкого доступа к информации.

Постоянно совершенствуйте и обновляйте¶

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

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

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

Заключение:¶

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