Вы работаете над программным проектом, возможно, это не новая ситуация, если вы читаете это, и вы сталкиваетесь с конкретными функциями, необходимыми для вашего проекта. Будучи эффективным (и ленивым) разработчиком, которым вы являетесь, вы понимаете, что эта функциональность достаточно общая, что, возможно, кому-то раньше была нужна, и для нее была написана какая-то библиотека. Зачем изобретать велосипед?
Таким образом, вы переходите на предпочитаемую поисковую систему, находите вероятного кандидата, просматриваете целевую страницу и делаете вывод, что эта библиотека соответствует вашим требованиям. Затем вы найдете ссылку на документацию и щелкните по ней. В конце концов, вам нужно выяснить, как его установить, настроить и фактически начать использовать в своем проекте. Есть только одна проблема: страница, на которую ссылается ссылка на документацию, содержит только сгенерированную документацию API. Вы сразу подумаете: с чего мне начать?
Вы можете сделать шаг назад, выполнить поиск в репозитории управления версиями и найти файл с именем что-то вроде READMEINSTALLEXAMPLE Даже если вам удастся установить и настроить библиотеку, куда вы пойдете? Какой конкретный фрагмент кода обеспечивает точку входа в логику библиотеки? Вам нужно сделать что-то конкретное, чтобы загрузить или загрузить его? Есть ли что-то еще, что вам нужно сделать, прежде чем использовать его, помимо добавления его в структуру каталогов вашего проекта и изменения нескольких параметров конфигурации?
Вы можете в течение короткого времени бездельничать, сканируя документы API на предмет более существенной информации, чем имена классов и методов или типы параметров и возвращаемых значений. Вы можете сделать обоснованные предположения и попробовать что-то, чтобы закрепиться в работе библиотеки. Если у вас ничего не получится, настанет момент, когда вы поднимите руки в воздух и перейдете к следующему варианту.
Если вы пишете код, которым вы будете делиться с другими, поставьте себя на их место. Не позволяйте вашему проекту потерять потенциальных пользователей, членов сообщества и возможных участников из-за недостатка документации.
Контент король
«Контент — король» — доминирующий принцип в SEO (поисковая оптимизация). То же самое относится и к вашей документации: она должна быть переполнена информацией с типичными случаями использования, примером кода, предупреждениями о потенциальных подводных камнях и так далее. К сожалению, резиновая утка не так эффективна, как при отладке, потому что утка не дает обратной связи, и это не та проблема, где решения, скорее всего, будут обнаружены в ваших объяснениях.
Сделайте первую попытку того, что вы считаете хорошей документацией, а затем сделайте то, что делают все хорошие разработчики: бета-тестирование. Пусть несколько человек прочитают его, попробуют использовать библиотеку и предоставят обратную связь. Спросите их, какие части не были ясны или могли быть изложены или организованы лучше, где не хватало информации, какая дополнительная информация могла быть полезна и т. Д. Итеративно применяйте улучшения до запуска вашего проекта, чтобы большинство потенциальных проблем было решено заранее или вскоре после.
Открой это
Создание качественного контента — это большая работа, особенно в начале, но это также большая часть того, что привлекает первых пользователей. Как только проект будет запущен, люди могут захотеть внести свой вклад в документацию, если у них нет времени или навыков для принятия исходного кода. Однако, если у них нет способа внести изменения в вас, это может быть очень неприятным для вклада. Вы этого не хотите.
Существует два основных способа открытия документации, чтобы помочь пользователям поддерживать ее актуальность и достаточность для своих нужд: использовать вики или поддерживать ее в репозитории контроля версий.
Такие вики, как DokuWiki , MediaWiki и (для крупных компаний) Atlassian Confluence, как правило, легко настраиваются и настраиваются в соответствии с вашими потребностями. Вы можете разрешить кому-либо редактировать их или потребовать, чтобы пользователи сначала зарегистрировались. Большинство вики поддерживают историю версий каждой страницы, позволяя пользователям отменить злонамеренные изменения и проверить, кто внес изменения и почему они были сделаны. Может быть небольшая кривая изучения в отношении того, как использовать вики, но в остальном браузерные интерфейсы очень доступны для потенциальных участников.
Использование репозитория контроля версий позволяет вести документацию параллельно с вашим исходным кодом. Экспериментальные ветки с дополнениями или изменениями могут быть легко переданы и проверены коллегами перед объединением. Интерфейсы, подобные предоставляемым GitHub, могут упростить отслеживание предлагаемых вкладов, в то же время ограничивая изменения выбранным числом участников с правами на слияние для обеспечения гарантии качества. В зависимости от формата и цепочки инструментов, которые вы выберете (например, Docbook и PhD ), также будет проще сделать вашу документацию доступной в нескольких форматах, таких как HTML, PDF или ePub, и интегрировать документацию в процессы сборки и непрерывной интеграции.
Какую бы документацию вы ни предоставили, она также должна быть максимально доступной. Не требуйте от пользователя проходить процесс регистрации для доступа к нему. Размещайте общедоступный текст или HTML-копию для пользователей, чтобы получить доступ к ней в браузере, вместо того, чтобы требовать, чтобы они загружали ее полностью для просмотра в отдельной программе. Это имеет дополнительный бонус, позволяющий поисковым системам индексировать его. Сделайте разделы в HTML-копиях связанными с помощью якорей, чтобы пользователи могли легко ссылаться на них по отдельности.
Документация, Документация, Документация
Стив Баллмер стал довольно печально известным для его пения «Разработчики, разработчики, разработчики» . Это, в конце концов, представитель того, чего обычно хотят люди, начинающие программные проекты: сообщество разработчиков, которое должно сформироваться вокруг этого проекта, внести свой вклад в него и помочь развить его и сделать его лучше, чем вы могли бы в одиночку. Хотя это не единственное средство для достижения этой цели, весьма вероятно, что документация не помешает вам в достижении этой цели, если она хороша и хорошо продумана.
Обращайте внимание на технические ресурсы для написания статей, которые помогут вам в написании документации. Такие ресурсы существуют во многих формах, таких как курсы в вашем местном университете, записи в ныне несуществующем блоге Кэти Сьерры « Создание страстных пользователей », раздел «Общайтесь!» Книги «Прагматичный программист» , рекомендации для авторов « Пропавшего руководства» и презентация Рича Боуэна. Лучше FM . Они могут также прийти в менее очевидных формах, таких как книга Гарр Рейнольда Presentation Zen , которая охватывает создание провокационных визуальных презентаций — независимо от конечной среды, книга научит вас представлять информацию способами, которые делают ее интересной и информативной для ее потребителя.
Резюме
Короче говоря, приложите значительные усилия, чтобы документировать свой проект и сделать его пригодным для использования другими. Вас может удивить, насколько большую поддержку вы получаете в разработке, просто потому, что вы вкладываете в это время и силы. Несмотря на это, это будет время и усилия, потраченные хорошо.