Документация пользователя для Joomla расширения
Документация может носить форму онлайн документов, PDF файлов, видео-роликов и печатных руководств. В ней должна быть описана каждая функция вашего расширения. Документация хорошего качества должна отражать актуальные возможности текущей версии расширения. В идеале она должна иметь тематические сноски (якоря) и иметь возможность поиска по фразе. Не секрет, что большое кол-во разработчиков под Joomla! создают свои руководства с помощью Joomla!
- Руководство пользователя Akeeba Backup - пример шикарной документации (англ.)
- A Review of Other Help Authoring Tools (рекомендация по подоготовке документации - англ.)
Определите свою аудиторию
Это не так просто как кажется. Ведь это может быть пользователь средней подготовки, более продвинутый дизайнер, коллега-разработчик или системный администратор. Вам нужно учитывать, что большинство пользователей не будут изучать документацию, не попробовав прежде сам программный продукт. В большинстве случаев к руководству обращаются в случае, когда что-то неожиданно случается и им необходима помощь в настройке.
Структурируйте документацию
Нет смысла писать документацию не имея структурного плана. Вы программируете, не имея поставленных задач и плана? Вероятно, что нет. То же самое и в случае подготовки руководства пользователя. Ниже приводится пример структуры документации:
- Вступление
- Предупреждение об отказе от ответственности, версии и лицензионное соглашение
- Оглавление
- Содержимое руководства
- Установка
- Обновление
- Деинсталляция
- Пошаговая инструкция
- Материалы и источники, глоссарий и дополнительные требования
- Контакты и техническая поддержка
- Авторские права и установление авторства
1. Вступление
Краткое описание предназначения расширения, какие задачи оно выполняет. Описание возможностей расширения.
2. Предупреждение об отказе от ответственности
Вам нужно четко пояснить, что вы не несёте ответственности за веб-сайт клиента и не принимаете претензий по поводу неработоспособности сайта. Укажите текущую версию вашего продукта. Укажите условия лицензирования ясно и приведите ссылки на подходящие ресурсы.
3. Оглавление
Приступайте к подготовке этой части после того как руководство будет написано и завершено. При каждой доработке и обновлении документации, содержимое также потребуется корректировать в соответствии с внесенными изменениями.
4. Содержимое руководства
Может отличаться в зависимости от проекта, однако необходимо упомянуть об общих моментах:
- Процесс установки (автоматический и ручной)
- Процесс деинсталляции (автоматический и ручной)
- Процесс обновления расширения
- Объяснение каждого меню / режима в вашем расширении
- Пошаговое руководство Сопровождающие видео-уроки будут весьма полезны. Если вам не нравится, как звучит ваш голос, попробуйте программу типа Captivate. Захват неподвижных изображений с экрана и оформление их в иллюстрирующие эскизы поможет пользователю не пропустить последовательность действий и следовать согласно руководству.
- Сложные и трудоемкие моменты в настройке (упомянуть о потенциальных сложностях, которые могут возникнуть у пользователей)
5. Материалы и источники (Reference Materials)
Опишите каждый технический термин, который может использоваться в документации. Приведите ссылки на полезные ресурсы. К примеру, если у вас упоминается RegEx (сокращенно от Regular Expressions – регулярные выражения), объясните что это такое и приведите ссылку на источник (в данном случае http://www.regular-expressions.info). Если вы ссылаетесь на права доступа к файлам, уделите время и объясните как их можно изменить в вашей любимой FTP программе.
6. Контакты и информация о дополнительной технической поддержке продукта
Если у вас используется форум, приведите ссылку на него. Если поддержка продукта осуществляется на основе подписки на определенный период, приведите ссылку на страницу с выбором тарифного плана. Если вы не планируете осуществлять поддержку продукта вне документации, четко об этом упомяните. CMS Joomla! поддерживается энтузиастами и не каждый разработчик расширения имеет возможность оказывать поддержку программному продукту.
7. Авторские права и установление авторства
Если вы этого еще не сделали, защитите авторские права и на продукт и на документацию. Укажите свое отношение к продукту или, в случае отсутствия такового, к Joomla проекту.
Создайте последовательный стиль для руководства
Определитесь как форматировать код. Возможно, вы решите выделять кликабельные пункты жирным шрифтом. Возможно заголовки разделов всегда будут обрамлены в <H2> теги. Каким стилем оформлять внешний вид документации – решать вам. Важно соблюдать последовательность и выдерживать оформление в едином ключе. Создайте собственный стиль оформления и строго следуйте этим правилам в рамках всей документации!
Приступайте к подготовке документации!
Не пытайтесь за один раз подготовить документацию к целому проекту. Разбейте подготовку на несколько мелких этапов, чтобы она была в процессе подготовки. Большинство документаций всегда в «процессе подготовки».
