Сталкивались ли вы когда нибудь с долгим поиском документации к используемой библиотеке или пакету? Я считаю странным, что исходный код не распространяется с пользовательской документацией. Ведь она такая же важная часть кода, как тесты или зависимости. Без хорошей пользовательской документации мы можем «убить» уйму времени на анализ кода и комментариев. Так почему бы не хранить пользовательскую документацию вместе с исходными кодами программы? Речь не о DocBlock и генерацию документации по API проекта, я говорю именно о пользовательской документации, которую мы так любим за последовательное повествование и множество примеров.
В этой статье я приведу один из способов хранения пользовательской документации вместе с исходными кодами программы так, чтобы это было удобно как для разработчиков, так и для пользователей.
В отличии от документации, добавляемой прямо в исходные коды (в виде комментариев), пользовательская документация более «user-ориентированная», если можно так выразится. Представьте, что вы долго искали подходящую библиотеку и вдруг коллега назвал ту, которая «может вам подойти». Вы быстро находите ее на GitHub, но с чего начать? Хорошо если в корне есть файл README.md, но даже ознакомление с ним может оставить множество вопросов. Обычно все заканчивается одним исчерпывающим примером (если библиотека не большая) или ссылкой на официальную документацию в виде Web-сайта или PDF документа. После доступа к одному из этих ресурсов вы вздыхаете с облегчением, внимательно читаете несколько страниц, изучаете пятерку примеров и начинаете уверенно пользоваться библиотекой.
Использование Web-сайта или документа в качестве пользовательской документации это хорошее решение, но у него есть несколько минусов:
Вы храните unit-тесты вашего проекта вместе с кодом или в отдельном репозитории? Обычно они находятся в каталоге tests и являются неотъемлемой частью проекта. С документацией так же. Она — часть вашего проекта, но в отличии от тестов, она нужна пользователям не для проверки работоспособности вашего решения, а для быстрого и безболезненного ознакомления с ним.
Я предлагаю выделить для пользовательской документации отдельный каталог в вашем проекте. Пусть он называется docs и содержит файлы с расширением md (почему выбран именно Markdown вы узнаете позже). Полезно так же снабдить вашу пользовательскую документацию «точкой входа» — это файл оглавления, с помощью которого пользователям будет проще ориентироваться в этом каталоге. Я предпочитаю называть этот файл index.md и записывать в него список ссылок на остальные файлы в этом каталоге.
Рекомендую так же использовать файл «Введение» (getting-started.md), который можно использовать для «быстрого старта». В нем должны быть кратко и доступно описаны основные возможности вашего решения с примерами и комментариями. Информации в этом файле должно хватить для того, чтобы начать пользоваться вашим решением на пользовательском уровне.
Остальные файлы должны содержать подробное описание компонентов вашего решения, подробные примеры использования и возможные проблемы, с которыми может столкнуться пользователь. Лучше, чтобы эти файлы не были связаны друг с другом, чтобы пользователь мог начать изучение того компонента, который он считает нужным.
После того, как пользовательская документация будет готова, добавьте в корень вашего проекта файл README.md, в котором будет ссылка на «точку входа» вашей документации.
Теперь проект можно коммитить и заливать в ваш репозиторий. Если это GitHub, то помимо исходного кода, пользователи получат качественно оформленную пользовательскую документацию. В качестве примера могу предложить мое решение в области роутинга CLI-запросов, в котором использовался подход, предлагаемый в статье.
Так как вся документация находится в репозитории, на нее удобно ссылаться извне по ссылке вида: https://raw.githubusercontent.com/Bashka/bricks_cli_routing/master/docs/call.md — а если «прикрутить» сюда Web-интерфейс, то можно получить полноценный Web-сайт без необходимости переноса документации. Удобно не правда ли?
Более того, если вы переместите документацию из каталога docs в каталог docs/ru, то позволите вашим пользователям переводить ее просто добавляя новые каталоги и копируя в них переведенные файлы документации.
Если вы пишите небольшие OpenSource решения, то попробуйте этот способ хранения документации. Он может показаться чем то очевидным, но им редко кто пользуется. Возможно это обусловлено тем, что проект пишут одни люди, а пользовательскую документацию другие.
В этой статье я приведу один из способов хранения пользовательской документации вместе с исходными кодами программы так, чтобы это было удобно как для разработчиков, так и для пользователей.
Многим статья может показаться «капитанской». Если вы почувствуете на своих щеках соленые брызги и услышите шум волн, немедленно прекратите чтение!
Многим статья может показаться «капитанской». Если вы почувствуете на своих щеках соленые брызги и услышите шум волн, немедленно прекратите чтение!Пользовательская документация
В отличии от документации, добавляемой прямо в исходные коды (в виде комментариев), пользовательская документация более «user-ориентированная», если можно так выразится. Представьте, что вы долго искали подходящую библиотеку и вдруг коллега назвал ту, которая «может вам подойти». Вы быстро находите ее на GitHub, но с чего начать? Хорошо если в корне есть файл README.md, но даже ознакомление с ним может оставить множество вопросов. Обычно все заканчивается одним исчерпывающим примером (если библиотека не большая) или ссылкой на официальную документацию в виде Web-сайта или PDF документа. После доступа к одному из этих ресурсов вы вздыхаете с облегчением, внимательно читаете несколько страниц, изучаете пятерку примеров и начинаете уверенно пользоваться библиотекой.
Пользовательская документация — это лицо вашего проекта. Чем она доступнее, тем меньше пользователей бросят идею изучения вашего решения из-за проблемы новизны.
Пользовательская документация — это лицо вашего проекта. Чем она доступнее, тем меньше пользователей бросят идею изучения вашего решения из-за проблемы новизны.Использование Web-сайта или документа в качестве пользовательской документации это хорошее решение, но у него есть несколько минусов:
- Документация отделена от проекта и, возможно, пользователю будет сложно получить к ней доступ
- Ответственность за пользовательскую документацию лежит полностью на плечах разработчика. Если пользователь найдет ошибки или опечатки в ней, ему будет сложно (относительно предлагаемого в этой статье решения) связаться с разработчиком и сообщить ему об этом
- Если пользователь решит помочь разработчику и перевести документацию на другой язык, это будет так же проблематично сделать
- Документация может стать недоступной по техническим причинам (упал Web-сайт, потерялась ссылка на документ т.д.)Потому сейчас я постараюсь убедить вас в пользе хранения пользовательской документации прямо внутри проекта.
Как тесты
Вы храните unit-тесты вашего проекта вместе с кодом или в отдельном репозитории? Обычно они находятся в каталоге tests и являются неотъемлемой частью проекта. С документацией так же. Она — часть вашего проекта, но в отличии от тестов, она нужна пользователям не для проверки работоспособности вашего решения, а для быстрого и безболезненного ознакомления с ним.
Я предлагаю выделить для пользовательской документации отдельный каталог в вашем проекте. Пусть он называется docs и содержит файлы с расширением md (почему выбран именно Markdown вы узнаете позже). Полезно так же снабдить вашу пользовательскую документацию «точкой входа» — это файл оглавления, с помощью которого пользователям будет проще ориентироваться в этом каталоге. Я предпочитаю называть этот файл index.md и записывать в него список ссылок на остальные файлы в этом каталоге.
Пример
1. [Введение](./getting-started.md)
2. [Обработка файлов](./files.md)
3. [Работа в сети](./network.md)
Рекомендую так же использовать файл «Введение» (getting-started.md), который можно использовать для «быстрого старта». В нем должны быть кратко и доступно описаны основные возможности вашего решения с примерами и комментариями. Информации в этом файле должно хватить для того, чтобы начать пользоваться вашим решением на пользовательском уровне.
Остальные файлы должны содержать подробное описание компонентов вашего решения, подробные примеры использования и возможные проблемы, с которыми может столкнуться пользователь. Лучше, чтобы эти файлы не были связаны друг с другом, чтобы пользователь мог начать изучение того компонента, который он считает нужным.
Прямо в репозиторий
После того, как пользовательская документация будет готова, добавьте в корень вашего проекта файл README.md, в котором будет ссылка на «точку входа» вашей документации.
Пример
# Bricks.Cli.Routing
Пакет позволяет работать с данными, получаемыми при вызове PHP интерпретатора из
командной строки. Он так же реализует маршрутизацию на основе опций вызовов
командной строки.
## Установка и Автозагрузка
Этот пакет сопровождается файлом [composer.json][], что позволяет использовать
[Composer][] для его инсталляции и автозагрузки.
Так же можно установить его загрузив [исходные коды][] пакета в виде Zip архива
или клонировав этот репозиторий. Все компоненты этого пакета загружают
зависимости автоматически.
Перед использованием рекомендуется выполнить тестирование с помощью утилиты
[PHPUnit][] вызвав ее в корневом каталоге пакета.
## Зависимости
Этот пакет зависит от интерпретатора PHP версии 5.5 или выше.
## Поддержка
Если у вас возникли сложности или вопросы по использованию пакета, создайте
[обсуждение][] в данном репозитории или напишите на электронную почту
<Artur-Mamedbekov@yandex.ru>.
## Документация
Пользовательскую документацию можно получить по [ссылке](./docs/index.md).
Документацию API можно получить из исходных кодов пакета или с помощью утилиты
[Doxygen][].
[composer.json]: ./composer.json
[Composer]: http://getcomposer.org/
[исходные коды]: https://github.com/Bashka/bricks_cli_routing/releases
[PHPUnit]: http://phpunit.de/
[обсуждение]: https://github.com/Bashka/bricks_cli_routing/issues
[Doxygen]: http://www.stack.nl/~dimitri/doxygen/index.html
Теперь проект можно коммитить и заливать в ваш репозиторий. Если это GitHub, то помимо исходного кода, пользователи получат качественно оформленную пользовательскую документацию. В качестве примера могу предложить мое решение в области роутинга CLI-запросов, в котором использовался подход, предлагаемый в статье.
Так как вся документация находится в репозитории, на нее удобно ссылаться извне по ссылке вида: https://raw.githubusercontent.com/Bashka/bricks_cli_routing/master/docs/call.md — а если «прикрутить» сюда Web-интерфейс, то можно получить полноценный Web-сайт без необходимости переноса документации. Удобно не правда ли?
Более того, если вы переместите документацию из каталога docs в каталог docs/ru, то позволите вашим пользователям переводить ее просто добавляя новые каталоги и копируя в них переведенные файлы документации.
Пока все
Если вы пишите небольшие OpenSource решения, то попробуйте этот способ хранения документации. Он может показаться чем то очевидным, но им редко кто пользуется. Возможно это обусловлено тем, что проект пишут одни люди, а пользовательскую документацию другие.