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

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

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

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

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

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

Когда речь идет об учебниках, "как сделать", объяснениях и ссылках, в чем разница?

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

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

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

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

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

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

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

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

Она позволяет создать лучший опыт внедрения для ваших клиентов.

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

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

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

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

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

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

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

Это поможет вам поддержать собственную команду.

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

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

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

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

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

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

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

5. Пишите документацию, содержащую повторения там, где это необходимо.

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

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

8. Пишите документацию, которую легко обнаружить и понять.

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

Примите решение о том, что вы должны записать.

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

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

Создайте основу.

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

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

Всегда используйте преимущества надежных мультимедийных технологий.

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

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

![] (https://cdn.docsie.io/workspace_8D5W1pxgb7Jq3oZO7/doc_IDYTWOaZCuq9mWwra/file_Tp5KRnREeB4BWVdBn/679dc5ee-07ce-4579-b1e1-39f8afa64dceSnag_73f0470f.png)

Убедитесь, что она доступна для поиска.

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

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

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

Постоянно стремимся к улучшению и обновлению

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

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

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

![] (https://cdn.docsie.io/workspace_8D5W1pxgb7Jq3oZO7/doc_IDYTWOaZCuq9mWwra/file_ICAmxGtiRnaADNias/228e6de7-cf2c-4104-ac68-5b9d5909d572Snag_73f34a8b.png)

Заключительные мысли:

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