В этой статье я приведу один из способов хранения пользовательской документации вместе с исходными кодами программы так, чтобы это было удобно как для разработчиков, так и для пользователей.
Многим статья может показаться «капитанской». Если вы почувствуете на своих щеках соленые брызги и услышите шум волн, немедленно прекратите чтение!
Пользовательская документация
В отличии от документации, добавляемой прямо в исходные коды (в виде комментариев), пользовательская документация более «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 решения, то попробуйте этот способ хранения документации. Он может показаться чем то очевидным, но им редко кто пользуется. Возможно это обусловлено тем, что проект пишут одни люди, а пользовательскую документацию другие.
Комментарии (39)
SirEdvin
31.10.2015 12:29+2Я считаю странным, что исходный код не распространяется с пользовательской документацией.
Почему?
Причина мне кажется весьма очевидной.
Исходный код уже написан, а составление для него документации — это отдельная задача.
Причем чем больше проект, тем нужно больше времени на это убить.
Delphinum
31.10.2015 13:12+2Те же аргументы можно привести относительно тестов. Код и без них может прекасно работать и на их составление прибется убить уйму времени, но их хранят вместе с исходниками.
SirEdvin
31.10.2015 13:15+1Я видел так же много кода без тестов.
Например, в официальном репозитории calibre, я не нашел тестов (может плохо искал).
Но тесты часто нужны самим разработчикам и пишутся ими во время разработки.
А пользовательскую документацию нужно писать отдельно в любом случае.Delphinum
31.10.2015 13:17+3Но тесты часто нужны самим разработчикам и пишутся ими во время разработки
Если вы пишете OpenSource сугубо для себя, то да, можно (возможно) обойтись без документации.
А пользовательскую документацию нужно писать отдельно в любом случае
Что же мешает делать это параллельно с написанием кода? Программирование через Readme сильно упрощает разработку.SirEdvin
31.10.2015 13:36+2Если вы пишете OpenSource сугубо для себя, то да, можно (возможно) обойтись без документации.
Мне кажется, не возможно, а почти наверняка она будет без документации.
Что же мешает делать это параллельно с написанием кода? Программирование через Readme сильно упрощает разработку.
Если я не ошибаюсь, это две разные задачи.Delphinum
31.10.2015 15:01+1Мне кажется, не возможно, а почти наверняка она будет без документации
Я пишу документацию на все мои решения, ибо потом возвращаться к ним становится проще.
Если я не ошибаюсь, это две разные задачи
Ну так и тестирование это другая задача, но параллельное их выполнение положительно сказывается и на обоих процессах.SirEdvin
31.10.2015 15:04Ну так и тестирование это другая задача, но параллельное их выполнение положительно сказывается и на обоих процессах.
То есть, когда вы пишите код, вы не запускаете его потом, что бы проверить, сработает ли оно?Delphinum
31.10.2015 15:10Код можно и запустить, но автоматические тесты для этого писать не обязательно.
khim
01.11.2015 03:33Разница между пользовательской документацией и тестами совсем в другом. Тесты (какие бы они ни были) помогают прежде всего разработчику, который «в теме». Пользовательская документация нужна там, кто ещё не въехал.
Хотя на самом деле писать пользовательскую документацию, конечно, нужно. И именно разработчику. Просто потому, что когда вы попытаетесь подробно описать «как этим пользоваться» и увидите весь тот ужас, который у вас выльется на бумагу, то вы пойдёте и причишите наконец хидеры и прочие интерфейсные файлы! А то и API подправите… А профессиональный документописатель этого сделать, конечно, не сможет.
Но вот уже полноценные мануалы и «поучительные истории» — тут да, тут, наверное, смешивать с разработкой не стоит.Delphinum
01.11.2015 13:46Но вот уже полноценные мануалы и «поучительные истории» — тут да, тут, наверное, смешивать с разработкой не стоит
Согласен. Пользовательской документации должно быть в меру, чтоб и пользователям было понятно, и разработчики не сильно отвлекались.
aikixd
31.10.2015 13:56Если вы пишите в стол, то делайте как хотите, но если вы пишите для людей, то и ваш код и документация должны быть соответсвующими. Ни раз натыкался на проекты, от которых пришлось отказаться из-за отсутсвия доков.
SirEdvin
31.10.2015 14:02+1Одним из главных недостатков Open Source является то, что слово должны тут не очень работает.
aikixd
31.10.2015 14:04-1Это свободный рынок, открытый код — это такой же товар. Если он плохого качества то не ждите репортов и коммитов.
SirEdvin
31.10.2015 14:08Зависит от того, зачем этот код.
Например, моды для minecraft часто без документации (readme файл не в счет, там просто описание).
Документация к инструменту для написания модов (Forge) плоховата, на самом официальном сайте полно устаревшей информации, про официальную вики страшно говорит, но…
Приходится с ним работать.
AlexZaharow
31.10.2015 13:54+2Я вас полностью поддерживаю, не смотря на очевидность. Лучше лишний раз напомнить разработчикам, что нужно писать пользовательскую документацию. Хотя разработчик думает, что «и так всё понятно» (много кода или мало), но даже он, переключившись на другой проект и через неделю вернувшись обратно уже сам будет плавать в своём коде и чесать лоб, зачем что-то было сделано? Меня уже не раз выручали такого рода документы, которые я сам же себе и писал. Ещё если бы и не лень было делать скриншоты, чтобы знать, что должно получиться в итоге.
Было бы правильно, если бы вы кроме обозначения проблемы вы провели бы анализ, откуда вообще берётся «нежелание» писать документацию? Я возьму на себя смелость заявить, что действительно трудно просто писать документацию, т.к. нет хороших инструментов для этого. На каждое простое действие (например, сделать скриншот и вставить его в справку) — целая задача, отвлекающая от написания документации — собственно, сделать скриншот, «обтравить» его стрелочками и надписями, «сохранить» в каталог, а потом ещё и в тексте (если это markdown) дать ссылку. Т.е. после таких мыслей садиться и писать документацию совсем не хочется. Если у вас есть какой-то набор инструментов, который позволяет вам упростить эту задачу, не могли бы вы поделиться им и рассказать нам бонусы от их применения? У меня например zim desktop wiki (для заметок), ditto (clipboard manager), fast stone capture (пачками плодить скриншоты и накапливать их в ditto, потом пачкой вставлять в zim). Но это мой личный набор.Delphinum
31.10.2015 15:05+1Отсутствие удобных инструментов это одна из проблем. Другой является неумение писать документацию. Часто разработчик относится к написанию документации как к написанию книги, старается подобрать слова, украсить их элементами могучего Русского языка и сделать красивое оформление, что превращает его в писателя.
AlexZaharow
31.10.2015 15:57+1Конечно. Но ведь и программистом человек становится не сразу. Много пробует, ошибается в итоге обретает чувство баланса и начинает писать код вполне нормально. Так и с документацией. Написал для себя, прочитал через неделю, заметил огрехи, поправил. Потом уже пишешь без этих огрехов. В написании документации есть большой плюс — начинаешь думать уже как пользователь и лучше понимаешь что и зачем есть в программе.
Исключительно из любопытства, если касаться технической стороны написания документации, не могли бы вы поделиться какими-то программками или удобными (на ваш взгляд) ресурсами, которые могут упростить написание документации?
iroln
31.10.2015 14:38+3В мире Python пользовательскую документацию обычно всегда пишут с использованием Sphinx, хранят в репозитории вместе с исходными кодами и автоматически хостят на ReadTheDocs. И всем хорошо. :)
lair
31.10.2015 14:54Во-первых, на гитхабе есть GitHub Pages, которые предназначены ровно для того, о чем вы пишете, но при этом позволяют не смешивать код и обобщенную документацию.
Во-вторых, для многих языков есть встроенные средства документирования, которые позволяют генерить необходимую информацию на основании разметки прямо в коде.Delphinum
31.10.2015 15:09+2Во-первых, на гитхабе есть GitHub Pages, которые предназначены ровно для того, о чем вы пишете
Когда я пишу небольшой проект, мне удобнее хранить и редактировать документацию параллельно с кодом проекта, а не переключаться на GHP. GHP это отличное решение, но, на мой взгляд, больше подходит для довольно крупных проектов, автору которых не лень рекламировать свой продукт.
Во-вторых, для многих языков есть встроенные средства документирования, которые позволяют генерить необходимую информацию на основании разметки прямо в коде
Я об этом упоминал в статье. Это документация API, а не пользовательская документация. В статье обсуждается второй тип документации.
vaniaPooh
31.10.2015 22:01+3Кстати, вики на Гитхабе — это тоже отдельный git-репозиторий, который можно отдельно версионировать.
Delphinum
31.10.2015 23:10+1Да, тоже хорошее решение. Проблема только в том, что это число GitHub'овское решение, и если ваш пользователь потеряет доступ к GH, то ему документация станет не доступна. Это может показаться глупым, интернет сегодня стабильный, а GH обещал долго жить, но когда начинаешь мотаться по командировкам в места без цивилизации, понимаешь что все должно быть на готове.
occam
01.11.2015 06:19Также пользователь может остаться без Вики, если проблемы случились на уровне как раз того приложения, которое и обеспечивало доступ в интернет. Предложенный способ хранения — это профессионализм, системность и просто вежливое отношение к пользователю.
massimus
31.10.2015 21:49В Perl документацию к каждому модулю принято писать прямо в нём:
https://en.wikipedia.org/wiki/Plain_Old_Documentation
Очень удобно (для пользователя, по крайней мере).Delphinum
31.10.2015 23:11Все таки, я считаю лучше разделять. Так и обрабатывать будет проще (на пример если захочится превратить доку в книгу), и читать удобнее (не нужно искать с какого же файла следует начать.
massimus
31.10.2015 23:55> если захочется превратить доку в книгу
Есть такие инструменты. Вот, например: https://metacpan.org/pod/distribution/App-Pod2Epub/bin/pod2epub
> с какого же файла следует начать
Все либы лежат в ./lib, главная называется так же, как и весь проект. Самое место для старта.
Но обычно искать не приходится, прежде чем пользоваться читаешь доки на сайте CPAN (там вся документация как раз из самих модулей показывается), а если уже поставил, то читаешь perldoc имя_модуля.
А для дополнительной документации, не относящейся к конкретному модулю/скрипту, в проект кладётся отдельный .pod
Вот пример: https://metacpan.org/pod/distribution/Dancer2/lib/Dancer2/Tutorial.pod
Вот ещё бы гитхаб их так же показывал, как cpan…Delphinum
01.11.2015 00:16читаешь доки на сайте CPAN
А если нет доступа к CPAN?PerlPower
01.11.2015 04:06Документация находится в самом коде библиотеки, которая у вас уже установлена. CPAN по сути красивая обертка для утилиты, которая выдирает документацию из кода и показывает в виде html. Документацию можно читать в простом текстовом редакторе. Ну или можете скормить либу утилите pod2html, которая идет в стандартной поставке perl, если вам надо как на cpan.
Delphinum
01.11.2015 13:48Доки в исходниках я люблю, но мне кажется их должно быть:
1. Немного
2. По существу
Считаю пользовательскую документацию лучше выносить. Так ее будет проще править и переводить силами самих пользователей.
Xao
01.11.2015 11:18Но ведь есть github wiki для каждого репозитория, более того, их можно клонировать себе, и вести как отдельный репозитрий, для удобства.
khim
02.11.2015 14:29Самая большая проблема любой документации — её актуальность. Любой другой репозиторий, кроме основного — это проблема синхронизации.
Потому вне репозитория должна жить только та документация, актуальность которой не будет поддерживаться. Скажем обзорные статьи, где ссылки на конкретные API — это только примеры. А всё остальное — должно быть в основном репозитории.
zahardzhan
02.11.2015 15:41Мне кажется в вашем примере с роутингом отдельная документация в формате маркдаун это оверкил. Javadoc-образных средств документирования и грамотного ООП-дизайна для подобных программ хватает с головой (с учетом того что они будут разрабатываться и использоваться в основном как библиотеки из специализированных IDE).
Я сейчас тоже экспериментирую с документацией, только там подход немного другой. Весь проект состоит из одного единственного README-файла документации, и программа на языке высокого уровня генерируется непосредственно из README-файла с помощью IDE, то есть отдельных исходников как таковых вообще нет.Delphinum
02.11.2015 15:45Мне кажется в вашем примере с роутингом отдельная документация в формате маркдаун это оверкил
Отчасти соглашусь. У меня есть пакет с 1 файлом и 2 файлами документации ) Часто можно обойтись DocBlock-комментами в стиле Javadoc.
Весь проект состоит из одного единственного README-файла документации, и программа на языке высокого уровня генерируется непосредственно из README-файла с помощью IDE
IDE дали искуственный интеллект? )zahardzhan
02.11.2015 17:24Эта IDE была разработана в Лаборатории Искусственного Интеллекта MIT, так что да ) Вот черновик, можете глянуть, но смотрите быстрее пока я не закрыл доступ gitlab.com/zahardzhan/well-tuned-emacs
Delphinum
02.11.2015 17:27я там не зареган, потому — спасибо, нет )
zahardzhan
02.11.2015 18:38Вообще, если интересуетесь документацией ИТ-проектов, посмотрите на TeX, потому что он эпически документирован во всех отношениях www.dropbox.com/s/868kii13wtifswx/tex.pdf?dl=0 www.dropbox.com/s/ov098y98q8wcyum/tex.web?dl=0 www.dropbox.com/s/mw24dccitb8nee2/TeXbook.pdf?dl=0
DevMan
имхо, намного удобнее связка в виде доксетов + вьюер для них (dash, velocity, zeal).