Этой статьей я начинаю серию публикаций, посвященных инструментам создания и ведения документации. Весь набор инструментов можно условно разделить на два типа: онлайн и оффлайн инструменты. К первому типу относятся сервисы, размещенные на вашем или стороннем сервере. Такая документация удобна тем, что создается и редактируется она удаленно и доступна сразу после сохранения всем пользователям. Примерами таких инструментов могут служить:
- Wiki-документация.
- Zendesk.
- Naturaldoc.
- Confluence.
Ко второму типу относятся программы и редакторы, устанавливаемые на компьютер техническому писателю. В результате их использования получается документ в одном из распространенных форматов: doc, pdf, chm и т.п. Для создания документации используются как классические редакторы вроде «MS Word», так и специализированные, например «Doc-o-Matic».
Здесь речь пойдет о создании документации в Wiki, а именно в её подвиде «DokuWiki».
Пара слов о «DokuWiki»
«ДокуВики» (DokuWiki) — полностью совместима со стандартами обычной вики. В силу простого и универсального синтаксиса использовать её достаточно легко. Для её работы не требуется создания СУБД, т.к. все данные сохраняются в обычных текстовых файлах. Чаще всего она используется для разработки документации командой разработчиков.
Имея настраиваемый набор прав «ДокуВики» отлично подходит для создания документации, которой будут пользоваться не только сотрудники одной компании, но и партнеры или другие пользователи. Помимо простого синтаксиса (о котором речь пойдет в следующей статье) «ДокуВики» имеет большой набор плагинов, с помощью которых существенно расширяется имеющийся функционал. Плагинам, которые я использую в одном из проектов, будет посвящена так же отдельная статья. Теперь же давайте пройдемся по основным возможностям «DokuWiki».
Системные требования для установки «DokuWiki»
- Веб-сервер с поддержкой PHP (чаще всего используется Apache).
- PHP 5.2 или выше. Чтобы в документации изменять размер изображений нужно установить PHP-расширение GD или Image Magick.
- Безопасный режимом PHP должен быть включен.
- «ДокуВики» корректно отображается во всех современных браузерах.
Основные функции
- Простой в использовании редактор страниц и разделов.
- Бесконечный архив изменений. Архив позволяет не только просматривать все изменения, но и сравнивать между собой измененные версии.
- Рассылка уведомлений на почту об изменениях в документации.
- Добавление изображений в текст документации.
-
Удобные внутренние ссылки.
- Автоматическое составление меню раздела по его заголовкам.
Редактор документации
В «DokuWiki» встроен достаточно мощный редактор, с помощью которого можно создавать полноценные страницы. Редактор расширяем за счет плагинов, дающих дополнительные возможности при редактировании Wiki. Редактор не поддерживает обычные html теги, но его собственный синтаксис достаточно универсален и позволяет создавать полноценные веб-страницы.
«ДокуВики» и поисковая оптимизация
«ДокуВики» может использоваться не только для создания закрытой документации. Если вы делаете массовый продукт и документация к нему лежит в открытом доступе, то она может служить дополнительным источником трафика на ваш сайт. Кроме того, «ДокуВики» можно использовать для создания сайтов или блогов, при этом вопрос поисковой оптимизации также будет вставать перед вами.
Существуют три основных составляющий SEO-оптимизации:
- Метазаголовки (keyword, description).
- Контент (содержимое страницы).
- URL страницы.
Метазаголовки создаются в DocuWiki с помощью плагинов «Meta» или «Tag». Однако стоит иметь ввиду, что поисковыми системами придается очень маленький вес содержимому метазаголовков.
Содержимое страниц зависит полностью от того кто занимается их наполнением и тут важно принимать во внимание основные рекомендации по написанию статей. Со своей стороны «ДокуВики» создает четкие и правильно структурированные HTML страницы, которые легко и просто анализируются поисковыми роботами. Кроме того, если ваша документация открыта для других пользователей в «ДокуВики» существует защита от спама — вы можете настроить через какое количество дней новая статья станет доступна для индексации поисковыми роботами.
Для приведения URL к нормальному виду используются преобразования на стороне сервера или в настройках самой Wiki. Подробнее об этом можно прочитать в документации.
Создание технической документации в DokuWiki. Синтаксис (часть 2)
Создание технической документации в DokuWiki. Полезные плагины (часть 3)
Создание технической документации в DokuWiki. Вопросы с которыми я сталкивался (часть 4)