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

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

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

Когда Тим Бернерс-Ли (Tim Berners-Lee) создавал интернет, его целью было обеспечить удобный обмен информацией. Таким образом, логично организовать хранение документов на основе технологий интернета. Такие инструменты, как вики, Atlassian Confluence, Google Docs и Office 365, отлично подходят для работы в браузере. При выборе платформы для документации учитывайте следующее:

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

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

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

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

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

• Обратная связь. Читатели должны иметь возможность оставлять комментарии или примечания, чтобы дополнять текст.

• Вложения. Насколько удобно прикреплять дополнительные файлы (изображения, видео, PDF)? Такие данные лучше хранить вместе с документом, к которому они относятся.

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