В данной статье мы углубимся в написание документации для плагинов, тем и продуктов WordPress. Большая часть информации может быть применена к документации для других типов программного обеспечения, но мы остановим свой взгляд именно на специфичных для WordPress аспектах. Как показывает мой опыт, качество документации в плагинах и темах WordPress значительно различается – начиная от плохо задокументированных плагинов с однострочными readme-файлами и заканчивая продуктами с пользовательскими руководствами, API для разработчиков и исчерпывающими скринкастами. Все эти типы документаций встречаются в экосистеме WordPress. Многие плагины и темы созданы разработчиками, у которых нет времени писать документацию или нет денег для оплаты услуг копирайтера.
К сожалению, человек, который страдает больше всего от этого – разработчик. Николас Закас, писатель и фронтэнд-разработчик, указал в своем блоге на главную причину, почему хорошие JavaScript-библиотеки часто не имеют успеха:
Недостаточная документированность:
«Неважно, насколько привлекательна ваша библиотека и насколько продуман ее дизайн, но если вы единственный, кто понимает ее, она не принесет никакой пользы. Документированность подразумевает под собой не только автоматически сгенерированную справку по API, но и снабженные комментариями примеры и доскональные учебные руководства. Если все эти три пункта имеются в наличии, ваша библиотека может быть легко принята людьми».
Приняв условия Закаса за отправную точку, давайте посмотрим, как гарантировать то, что ваш продукт будет быстро принят людьми. Мы взглянем, в частности, на то, как обеспечить информативную документацию для конечных пользователей, сделав краткий экскурс в написание текстов. Но сначала давайте погрузимся в основы теории обучения.
Изучение предпочтений
Несколько лет назад я создал педагогический курс, в котором обучал людей написанию текстов для взрослых. Несмотря на то, что сейчас я уже не преподаю, я, тем не менее, вложил аспект теории обучения в свой процесс написании документации. VARK – это теория изучения предпочтений, акроним от слов visual, auditory, read/write и kinesthetic.
Теория VARK охватывает различные пользовательские предпочтения по получению и использованию информации, конечная цель которых – обучение, что делает эту теорию очень полезной при написании документаций. Нужно размышлять над тем, как ваши пользователи обрабатывают предложенную им информацию, и как сделать ее максимально простой и понятной для них. При написании текстов думайте обо всех способах, как пользователи взаимодействуют с информацией и обрабатывают ее; VARK утверждает, что люди делают это многочисленными способами.
Чтобы понять, чему именно вы отдаете предпочтение в обучении, необходимо пройти небольшой тест. Его результаты покажут вам, какой режим обучения для вас самый эффективный – либо тест покажет вам, что вы мультимодальны, то есть усваиваете информацию одинаково хорошо в разных режимах. Вообще, существует много разных теорий обучения, но именно эта мне кажется наиболее полезной при изучении различных типов документации, которые мне требуются в процессе работы над проектом.
В сущности, VARK показывает, что люди обучаются самыми разными способами, потому в любых педагогических занятиях мы должны думать о том, как сделать эти способы максимально полезными. Давайте посмотрим на различные предпочтения в сфере обучения и убедимся в том, что мы задействовали все из них.
Визуальный стиль обучения
Учащиеся с визуальными предпочтениями лучше всего усваивают информацию, полученную зрительным путем. На сайте VARK к такому стилю обучения относят следующие техники:
– изображения, плакаты и слайды;
– ведущие, использующие изображения или жесты;
– книги с изображениями и диаграммами;
– блок-схемы и графики;
– выделенный текст, многочисленные цвета и подчеркивание;
– символы и пробелы.
Указанные предложения касаются занятий в учебных помещениях, однако их очень просто перенести их к документациям. Учащиеся с визуальными предпочтениями выбирают целостный подход, пытаясь увидеть цельное изображение вместо разбиения его на дискретные компоненты. Они могут пробежаться взглядом по всему руководству или разделу документации, чтобы получить общее представление о предмете. Для таких учащихся лучше использовать следующие методики:
– используйте врезки, чтобы привлечь внимание к важным советам и примечаниям в тексте.
– добавляйте полезные скриншоты, создавайте надписи на них, оформляйте текст и создавайте сноски.
– используйте блок-схемы для иллюстрации процесса.
– выделяйте важные части текста, отмечайте ключевые фразы полужирным стилем.
– добавьте графики, подчеркивающей вашу точку зрения.
– создавайте скринкасты (к примеру, ролики, в которых человек объясняет что-либо читателям, стоя перед электронной доской).
Рекомендуемые типы документаций: различные учебные руководства, скринкасты, графика, инфографика.
Слуховой стиль обучения
Учащиеся со слуховыми предпочтениями лучше всего усваивают информацию через общение и прослушивание. На сайте VARK таким учащимся рекомендуют следующие техники:
– посещение занятий;
– участие в дискуссиях;
– разъяснение идей;
– использование магнитофона;
– припоминание интересных примеров;
– описание каких-либо вещей человеку, который с этим не сталкивался.
Поскольку онлайн-документация – это визуальное средство информации, определить стратегии, которые были бы применимы к учащимся, гораздо сложнее. Однако и здесь можно указать следующие техники:
– подкасты;
– скринкасты с подробным повествованием;
– интересные, применимые на практике примеры;
– чат-комнаты, такие как WordPress IRC, форумы поддержки или скриншаринг в Skype (даже если это не документации).
– вебинары.
Как показывает список, даже если ваша документация будет высоко детализирована, всегда найдутся люди, которые предпочтут скорее задать вопрос или что-то обсудить, нежели читать справки.
Рекомендуемые типы документаций: учебные руководства, скринкасты, подкасты, вебинары.
Чтение/конспектирование
Учащимся, предпочитающим читать или конспектировать, предложить документацию проще всего; они действительно любят учиться посредством чтения. Однако вместо того чтобы просто включать огромные блоки текста, можно как-то разнообразить информацию, сделать ее интересной. Вот некоторые предложения для этого:
– списки;
– заголовки;
– словари;
– глоссарии;
– определения;
– крупные блоки текста;
– эссе;
– руководства (компьютерные, технические и лабораторные).
Длинные документации – хороший способ заинтересовать таких людей, однако можно провести дополнительную работу, чтобы еще сильнее увлечь их:
– используйте упорядоченные и неупорядоченные списки;
– используйте теги для заголовков;
– включайте описания в сноски и врезки;
– включайте ссылки на определения;
– создавайте пользовательское руководство;
– создавайте глоссарий;
– выпускайте краткие руководства и электронные книги.
Рекомендуемые типы документаций: учебные руководства, электронные книги, руководства, глоссарии, ссылки.
Кинестетический стиль обучения
Учащиеся с кинестетическими предпочтениями лучше всего усваивают информацию через выполнение каких-либо вещей. Они скорее постараются что-то сделать сами, нежели будут смотреть демонстрации. На сайте VARK таким учащимся рекомендуют следующие техники:
– использование всех ощущений (зрение, осязание, вкус, обоняние, слух);
– прохождение практик;
– практические примеры абстрактных принципов;
– примеры из реальной жизни;
– практический подход;
– метод проб и ошибок;
– изучение наборов предметов (виды камней, растений, раковин и т.д.)
– экспонаты, образцы, фотографии;
– советы (решения проблем и т.д.).
Какие виды документаций подойдут таким учащимся? Ответ здесь лежит на поверхности:
– пошаговые учебные руководства;
– ссылки на практические примеры;
– примеры из реальной жизни;
– интерактивные средства обучения;
– короткие, практичные советы;
– вебинары, связанные с практикой (исключающие абстрактные вещи).
Рекомендуемые типы документаций: практические учебные руководства, подсказки и хаки, варианты использования.
Мультимодальность
Примерно 60% населения не соответствует в точности ни одному из представленных типов. Если это верно для вас, то вы мультимодальны, то есть предпочитаете две, три или все четыре категории. Вы можете адаптироваться к проводимому стилю обучения и предложенным средствам информации.
Помимо этого, вы можете легко изменять свои предпочтения в зависимости от жизненного опыта. Разработчик, голова которого забита кодом, API и справками, может легко использовать кинестетическое обучение или обучение через чтение/конспектирование.
Итог
Суть такого погружения в теорию обучения проста: показать, что люди обучаются разными путями. Поэтому вам надо обязательно удостовериться в том, что ваша документация рассчитана на всех людей.
Иногда клиенты говорят мне, что они хотят получить скринкасты. Я спрашиваю их, смотрели ли они что-нибудь другое, и если их ответ – нет, то в таком случае я рекомендую им обратиться к иным формам документаций. Лично я считаю, что скринкасты слишком сложны для изучения; я предпочитаю читать учебные руководства перед началом работы. Все люди разные, поэтому если вы хотите, чтобы ваш продукт оказался полезным как можно большему числу людей, обязательно подумайте обо всех представленных предпочтениях в обучении.
К счастью, это очень просто сделать. Учебное руководство должно быть следующим:
– предложите людям с кинестетическими предпочтениями сделать что-нибудь на практике;
– обратитесь к людям с предпочтениями чтения/конспектирования с помощью создания упорядоченных и неупорядоченных списков, заголовков и сносок для определений.
– сноски также подходят людям с визуальными предпочтениями, потому вы можете разбавить их графикой, диаграммами и изображениями;
– полезные примеры несут в себе удобство для людей, предпочитающих слуховую информацию; чтобы поставить галочку рядом с четвертым типом людей, достаточно создать краткий скринкаст.
Не нужно тратить кучу времени на тщательное продумывание документации. Просто знайте, что варьирование методов здесь очень важно.
Какие типы документаций можно отметить?
Как вы, вероятно, догадались, видов документаций очень много. Документацией выступает что-то, описывающее ваш плагин, продукт или тему. Ниже приведены некоторые примеры документаций:
– справка;
– справка по API;
– комментарии и краткая документация;
– список требований;
– глоссарий;
– обзор архитектуры или дизайна;
– учебное руководство;
– краткое руководство;
– readme-файл;
– FAQ;
– справочное меню WordPress;
– подсказки;
– пользовательское руководство;
– руководство по поиску и устранению ошибок;
– скринкасты;
– книги и электронные книги;
– краткие советы и хаки;
– инфографика;
– вебинары.
Тип документации будет зависеть от двух вещей:
– от вида продукта;
– от вашей аудитории.
Многие WordPress плагины и темы разрабатываются преимущественно для конечных пользователей. Все эти плагины и темы редко выступают в качестве инструментов для разработчиков. Учитывая это, давайте посмотрим на то, как создать эффективную и продуманную документацию для конечных пользователей.
С чего начать?
Перед тем, как начать разработку любого типа документации, следует подумать о следующих вещах:
– Определились ли вы с тем, какие возможности будут реализованы?
Не стоит писать документацию, если вы продолжаете добавлять опции и вносить значительные изменения в код.
– Есть ли у вас четкий план?
Набросайте структуру. Точно так же, как дизайнер создает каркас будущего сайта, вы можете схематически набросать структуру вашей документации как для ее отдельных частей, так и для всей документации целиком. Это сделает документацию связной и логичной.
– Насколько резкой является кривая обучения?
Если ваш продукт представляет собой многогранное комплексное решение, вам понадобится разбить документацию на несколько разделов, которые будут идти в порядке роста сложности: сначала разделы, адресованные новичкам, потом разделы для всех пользователей, и, наконец, разделы для специалистов.
– Есть ли у вас связь с разработчиками?
Если вы сами являетесь разработчиком, то это прекрасно; в противном случае вам понадобится установить с ним связь. Сначала вам понадобится изучить продукт, у которого, скорее всего, отсутствует документация, то есть вам нужно будет задать некоторые вопросы разработчикам. Нет никакого смысла начинать работу над документацией, если разработчик собирается уехать в отпуск.
– Какова ваша цель?
Создается ли документация только для пользователей или же она преследует некоторые маркетинговые цели? Справка в формате doc будет бесполезной для продаж, чего нельзя сказать про учебное руководство, которое будет демонстрировать продукт потенциальным покупателям.
Вот некоторые советы по написанию текстов, которые вам необходимо держать в уме:
– Старайтесь сохранять простоту.
Этот совсем не тот случай, когда надо показывать свои писательские таланты или чрезмерную умудренность. Идеальная техническая документация должна быть четкой, лаконичной и цепляющей.
– Обращайтесь к пользователю во втором лице.
Например, «когда вы вошли в систему WordPress, перейдите к панели управления плагинами». Пишите так, будто читатель находится рядом, и вы объясняете ему весь ход действий.
– Придерживайтесь сути изложения.
Не выходите за границы темы, поскольку это может отвлечь пользователей.
– Учитывайте форматирование.
Возможно, вам потребуется выделить полужирным ключевые слова в каждом абзаце, отметить инструкции. Сохраняйте общий стиль форматирования на протяжении всего документа.
– Пишите в настоящем времени.
Опять же, пишите так, как будто человек находится рядом с вами, и вы общаетесь с ним.
– Подумайте о манере выражения.
Я рекомендую соблюдать дружеский тон, но вы можете выражаться так, как вам удобнее, чтобы это соответствовало остальному контенту сайта.
– Не бойтесь коротких абзацев.
Облачайте одну мысль в один абзац, чтобы сообщения не были запутанными.
– Будьте логичны.
Постепенно передавайте вашу информацию в логическом порядке, чтобы читатели могли следовать за вами по тексту.
– Корректируйте тексты.
Попросите, чтобы кто-нибудь перечитал ваши тексты. Свежий взгляд поможет найти ошибки, которые могли ускользнуть от вас.
Документация для конечных пользователей
Конечный пользователь – человек, который будет использовать ваш продукт. В среде WordPress меня лично просят сформировать документацию чаще всего именно для таких типов пользователей. Существует значительное разнообразие конечных пользователей, начиная от полных новичков и заканчивая опытными пользователями, а также разработчиками. Если они используют продукт (в противоположность его разработке), то мы можем их считать конечными пользователями.
При написании документации для конечных пользователей я всегда рекомендую ориентироваться на полных неофитов. В процессе этого вы должны убедиться в том, что раскрыли абсолютно все моменты. Более продвинутые пользователи могут изучить весь документ и взять из него то, что им требуется.
Исследуем и подготавливаем материал
Перед тем, как положить пальцы на клавиатуру, потратьте некоторое время на подготовку того, что вы хотите сделать и как вы хотите это сделать. На данный момент ваше программное обеспечение должно быть стабильным и практически готовым к работе. Очень хочется взять и кинуться писать документацию, чтобы скорее завершить ее. Однако стоит прислушаться к совету Майка Поупа, технического редактора Microsoft:
«Мы сказали разработчикам: «если что-то не задокументировано, то этого не существует». Все это не только должно быть задокументировано, но и должно быть объяснено и показано на примерах. Сделайте так, и люди будут заинтересованы – не вашей документацией, а вашим продуктом».
Отметьте для себя, что хорошая документация влияет на успех вашего программного обеспечения.
– Требуется ли вам руководство по инсталляции? Если ваш продукт не находится в хранилище WordPress тем или плагинов, я рекомендую подготовить универсальное руководство, которое покажет пользователям, как установить плагин или тему через функцию загрузки в WordPress или через FTP.
– Планируйте все заранее. Если ваша документация будет объемной, подумайте о ее структуре. Как пользователи будут переходить по ней? Как вы ее представите?
– Составьте список всех ресурсов, которые могут пригодиться пользователям (скажем, ссылки на FTP-клиент или текстовый редактор). Обязательно оставляйте ссылки на инструменты, которые вы рекомендуете к использованию.
– Выберите самый подходящий тип документации для продукта. Возможно, вы желаете создать общее руководство по установке или руководство по частным функциям. Применительно к плагинам электронной коммерции вы можете добавить следующие секции: «Как установить плагин электронной коммерции» или «Продажа ваших цифровых продуктов с помощью плагина электронной коммерции».
– Обеспечьте легкий доступ ко всем ресурсам и справкам, которые могут пригодиться пользователям. К примеру, при введении нового понятия можно сослаться на релевантную страницу вашего сайта или WordPress кодекса.
– Предугадывайте вопросы, которые могут возникнуть у пользователей. Если ваши пользователи будут настойчивыми и прочитают документацию, то они проведут гораздо меньше времени на форумах поддержки.
– Подумайте о том, как интегрировать вашу документацию в панель администратора WordPress. В WordPress 3.3, к примеру, контекстная справка была значительно улучшена, что стало идеальным местом для помощи пользователям.
– Определитесь со своими мыслями и придерживайтесь их. Не выходите за границы темы, иначе читатель может запутаться. Читатель должен покинуть документацию, получив ключевые идеи.
– Разбавьте текст примерами или различными историями, которые помогут пользователю взглянуть на текст с разных позиций. Это отличный способ подчеркнуть свою мысль.
Переходим к написанию
Помните, что цель документации состоит в том, чтобы помочь людям научиться быстро и эффективно пользоваться продуктом. Представьте себя в образе непрофессионального конечного пользователя и определите, что им потребуется для этого. Поставьте перед собой вопросы, которые могут возникнуть у конечного пользователя. Никогда не делайте предположений, что конечный пользователь обязан что-то знать; ваша задача – рассказать им об этом.
Посмотрите на свою документацию как на историю. Как любая хорошая история, она должна иметь начало, середину и конец. Ниже приведен обзор того, что стоит включать в каждую часть.
Вводный абзац очень важен. Он задает общий стиль документации и должен включать в себя следующее:
– познакомьте читателей с тем, что вы собираетесь рассказать;
– расскажите людям, как вы собираетесь это сделать;
– перечислите требования (к примеру, WordPress 3.3+);
– подведите итоги того, что читатель научится делать к концу документации (если это практическое руководство);
– перечислите ресурсы, которые могут пригодиться пользователю для каждого практического раздела.
Главная часть – стержень документа. Именно с нее читатели начинают обучение. Вот некоторые подсказки, позволяющие правильно написать основную часть:
– Если вы пишете пользовательское руководство, разбейте основную часть на несколько автономных разделов, связанных с разными темами. Дайте каждому разделу четкий, релевантный заголовок. Руководство пользователя по установке платежных систем может быть разбито на разделы “PayPal,” “PayPal Pro,” “Authorize.net” и т.д.
– Учебное руководство должно быть разбито на четко пронумерованные шаги, каждый из которых обладает своим заголовком. Каждый шаг должен быть логически связан с одной определенной задачей и должен вытекать из предыдущего шага. Добавьте все, что понадобится пользователю для выполнения задачи. В идеале, продвинутый пользователь должен понять, что ему нужно сделать, всего лишь изучив заголовки, в то время как новичкам придется это полностью прочитать. Учебное руководство по инсталляции WordPress плагина через FTP должно содержать следующие шаги:
1. Скачиваем плагин.
2. Загружаем плагин через FTP в wp-content/plugins.
3. Активируем плагин.
Этого было бы достаточно для подготовленного пользователя, в то время как основной текст окажет посильную помощь новичку.
– Используйте сноски, чтобы выделить важные участки информации. Я использую их для:
– полезных советов;
– определений и описаний;
– важной информации;
– продвинутых советов для более опытных пользователей.
– Используйте многочисленные скриншоты. Они очень полезны для людей с визуальными предпочтениями и людей, которые быстро пробегают взглядом по тексту.
– Подумайте над тем, чтобы подключить скринкаст для создания визуальных руководств.
– Используйте различные методы в каждом разделе документации, чтобы охватить все четыре типа аудитории. В итоге вам не понадобится создавать разные версии документаций для людей из каждой группы.
– Используйте подсветку синтаксиса для улучшения удобочитаемости кода. Если вы пишете свою документацию в WordPress, обратите свое внимание на плагин Syntax Highlighter Reloaded.
В заключении необходимо подвести итог того, что вы рассмотрели, а также предложить различную дополнительную информацию:
– если руководство достаточно объемно, содержит большое количество всестороннего материала, то в заключении можно напомнить пользователям о том, что вы рассмотрели с ними, и что они теперь уже должны знать. Здесь можно указать список основных пунктов или мыслей.
– Практическое учебное руководство можно закончить скриншотом или ссылкой на готовую работу.
– Предложите список ресурсов для дальнейшего изучения.
– Предложите список учебных руководств для дальнейшего изучения.
– Приведите ссылки на ваши форумы поддержки или на форму обратной связи.
Тестируем, Исправляем, Обновляем
Теперь, когда вы уже написали документацию, пришло время для того, чтобы протестировать, проверить ее и время от времени ее обновлять.
Если я пишу документацию для достаточно сложного продукта, я обычно прошу конечных пользователей протестировать ее для меня. Обычно в роли таких пользователей выступают люди, знакомые с WordPress, но не являющиеся разработчиками. Если я планирую написать учебное руководство, я попрошу их пройти через все шаги и выделить что-то, что им осталось непонятно, либо вызвало затруднения. Если вы используете фрагменты кода, они должны быть точными, поэтому попросите своего тестировщика, чтобы он проверил их на практике. Для пользовательского руководства я буду задавать вопросы, на которые тестировщик должен знать ответы.
Вооружившись предложениями тестировщика, я перейду к следующему этапу – проверке – и у меня уже будет список вопросов, который можно будет включить в обязательный FAQ.
Прочитайте весь документ и проверьте его. Вот то, на что следует обратить внимание:
– если вы протестировали документацию, добавьте в итоговый результат все изменения.
– избегайте многословия. К примеру, «теперь пришло время посетить панель администратора WordPress» можно заменить на «Войдите в панель администратора WordPress».
– исправьте все опечатки и грамматические ошибки.
– добавьте любые ссылки на то, что вы, возможно, пропустили.
Последний шаг в подготовке документации – это ее обновление. Оно может проводиться еженедельно, ежемесячно, ежегодно. В мире WordPress обновлять свою справку придется, скорее всего, каждый месяц. Обновление документации может потребоваться при:
– изменении пользовательского интерфейса WordPress (обновите скринкасты и скриншоты);
– добавлении новых возможностей и функций к вашему продукту;
– добавлении новых возможностей и функций к WordPress;
– получении отзывов пользователей о продукте.
Удобный плагин, которым я пользуюсь для отслеживания обновлений документации – Content Audit. Он работает с пользовательскими таксономиями, которые помогают структурировать контент. Также вы можете пометить разделы как «требующие обновления» прямо через пользовательский интерфейс WordPress.
Давайте взглянем на пример документации для конечных пользователей, которую я недавно завершил.
ManageWP
В конце 2011 года ко мне обратились ManageWP с предложением переделать их документацию. На тот момент их документация была довольно скудной и пестрила многочисленными грамматическими и орфографическими ошибками. Вот что сказал о ней Vladimir Prelovac:
«Наша начальная документация оставляла желать лучшего. Она не имела систематической структуры, большинство тем были добавлены спонтанно. Очень трудно было что-то по ней найти, она содержала в себе много ошибок, поскольку она была написана не носителями языка».
С первого взгляда было видно, что документация нуждается в общей переработке. Вот действия, которые я совершил.
- Я сделал полный обзор существующей документации, перечислил ее проблемы и предложил некоторые рекомендации:
- документация была написана в алфавитном порядке. Это означало, что новый пользователь не видел никаких логических связей в изучении материалов. Все было смешано, в итоге ничего нельзя было отыскать.
- многие абзацы раскрывали различные вопросы, что значительно усложняло изучение.
- не было скриншотов вообще.
- форматирование не изменялось, в итоге текст было трудно читать.
- Я порекомендовал реструктурировать документацию, чтобы сделать ее более логичной (скажем, начинаться она должна с раздела «Первые шаги», после чего должны идти разнообразные разделы).
- Я добавил в электронную таблицу Google список всех существующих руководств, разбив их по секциям. Затем мы уже определили порядок следования всех пунктов.
- Все руководства пользователя были переписаны согласно принципам, обрисованным в общих чертах выше.
- Мы изучили документы, чтобы добавить контент по продажам и маркетингу.
- Макет и дизайн для пользовательского руководства мы сделали более понятными для неопытных пользователей.
Результат вы можете увидеть, перейдя к пользовательскому руководству ManageWP. В будущем мы планируем улучшить документацию, добавить к ней видеофайлы, которые дополнят текст.
Документация для разработчиков
Документация для конечных пользователей предназначается людям, использующим ваш плагин или тему. Документация для разработчиков адресована людям, которые будут разрабатывать эти самые плагины или темы, расширять их или проводить их форкинг. Лично мне приходит гораздо меньше запросов по созданию документации для разработчиков WordPress; я подозреваю, это связано с тем, что большинство разработчиков и дизайнеров WordPress создают продукты для конечных пользователей. Иногда ко мне обращаются за тем, чтобы разработать документацию для проекта, который будет ориентироваться и на разработчиков, и на конечных пользователей – этот случай я рассмотрю ниже.
Я рекомендую разделять документацию для разработчиков и конечных пользователей. Конечные пользователи не должны видеть документы разработчиков; это только запутает их, и, в некоторых случаях, даже испугает. Конечно, ничто не мешает одной группе использовать документацию другой, поскольку группы не должны быть взаимоисключающими, но все равно очень важно проводить некоторые различия между ними, пусть даже при помощи уведомлений, как это сделано в кодексе WordPress.
Прекрасный пример документации для разработчиков – это недавно запущенный QueryPosts, являющийся удобным хранилищем WordPress кода.
Если вы создаете обширную документацию для разработчиков, используйте следующие инструменты:
– phpDocumentor;
– Pears (тема WordPress).
bbPress и их прекрасная встроенная документация
Плагин bbPress является одним из лучших примеров встроенной документации. Ниже приведен фрагмент файла bbpress.php, который выполняет загрузку перевода для текущего языка.
/**
* Load the translation file for current language. Checks the languages
* folder inside the bbPress plugin first, and then the default WordPress
* languages folder.
*
* Note that custom translation files inside the bbPress plugin folder
* will be removed on bbPress updates. If you're creating custom
* translation files, please use the global language folder.
*
* @since bbPress (r2596)
*
* @uses apply_filters() Calls 'bbpress_locale' with the
* {@link get_locale()} value
* @uses load_textdomain() To load the textdomain
* @return bool True on success, false on failure
*/
public function load_textdomain() {
// Allow locale to be filtered
$locale = apply_filters( 'bbpress_locale', get_locale() );
// Get mo file name
$mofile = sprintf( 'bbpress-%s.mo', $locale );
// Setup paths to current locale file
$mofile_local = $this->lang_dir . '/' . $mofile;
$mofile_global = WP_LANG_DIR . '/bbpress/' . $mofile;
// Look in local /wp-content/plugins/bbpress/bbp-languages/ folder
if ( file_exists( $mofile_local ) )
return load_textdomain( 'bbpress', $mofile_local );
// Look in global /wp-content/languages/ folder
elseif ( file_exists( $mofile_global ) )
return load_textdomain( 'bbpress', $mofile_global );
// Nothing found
return false;
}
Данный тип встроенной документации является полезным для разработчиков, использующих ваш код. Разработчик сразу может сказать вам, что делает указанный код. К тому же, человек видит определенные инструкции (например, поместить произвольные файлы перевода в глобальную папку с языками). Такой подход для продуктов с открытым исходным кодом делает код более понятным для широкой массы людей.
Вы должны писать встроенную документацию в процессе кодирования по многим причинам:
– если вы ведете разработку в одиночку, вы сможете написать документацию быстрее.
– сторонние люди смогут быстрее написать документацию;
– вы можете вернуться к коду в будущем и легко вспомнить, что вы делали;
– другие разработчики смогут провести форкинг вашего кода.
Infinity Theming Engine
Ко мне обратились PressCrew, чтобы я помог написать контент для их сайта и документацию по их движку для создания тем Infinity Theming Engine. Я догадывался, что это будет проблематично. В отличие от всего того, что я использовал в WordPress, движок Infinity использовал конфигурационные файлы для подключения и отключения различных возможностей и опций. Также он поддерживал сложные функции, такие как многочисленные дочерние темы, так что пришлось подумать, как вообще это можно использовать на практике.
Мы потратили значительное время, выявляя нашу аудиторию и выясняя, какие функции кому необходимо адресовать. Мы задали себе следующие вопросы:
– Зачем среднестатистическому пользователю WordPress может понадобиться Infinity?
– Нужно ли нам, чтобы среднестатистические пользователи WordPress могли использовать самые мощные возможности Infinity?
– Какая информация потребуется разработчикам, чтобы полностью использовать Infinity?
– Как сделать документацию полезной для разработчиков?
– Как вселить веру в Infinity?
Как только мы определили пользователей, нам понадобилось составить два типа документаций, каждый из которых будет обладать своими аспектами:
Иллюстративный
Поскольку нам требовалось показать разработчикам многочисленные способы работы с WordPress – использование .ini-файлов вместо прямого смешения с PHP – нам понадобилось сделать это интересно. Боу придумал помощников; персонажей, каждый из которых представляет свой конфигурационный файл. Мы использовали юмор и поп-культуру, чтобы изучение Infinity было увлекательным.
Практический
Как только разработчик изучил все аспекты Infinity, он может легко выполнить их на практике. Маршалл задокументировал каждую функцию и затем использовал phpDocumentor, чтобы создать документацию из исходного кода. Документация была написана в MarkDown и помещена сразу и в теме, и в библиотеку, таким образом, ее можно легко и быстро обновить. Предлагая доступ из библиотеки, Infinity обладает этой документацией и в консоли, поэтому разработчики могут быстро получить доступ к ней при работе над темой.
Основной сложностью являлась скорость, с которой обновлялся Infinity. Боу и Маршал попросили меня вступить в их команду еще на этапе бета-теста, чтобы я мог видеть основные изменения. Любые документы, которые я писал, через несколько недель уже были неактуальными. Я спросил Боу и Маршалла, какой совет они бы дали разработчикам в такой ситуации:
«Мы советуем делать основную схему всех планируемых возможностей. Когда возможность будет подключена к вашему продукту, обязательно задокументируйте ее на основе вашей схемы, до того как идти дальше».
Для таких крупных проектов, как Infinity, самым подходящим будет являться итеративный подход – документирование сразу при написании кода. Затем, когда уже возможности будут утверждены, вы сможете создать демонстрационную документацию.
Заключение: Сизиф и я
В греческой мифологии Сизиф – это король, который был осужден закатывать камень на вершину холма. Каждый раз, когда он достигает вершины, валун скатывается вниз. Он поднимается к вершине только затем, чтобы снова отступить от нее, и так далее, до бесконечности. Написание документации – как раз такой процесс.
Поскольку WordPress постоянно изменяется, приходится постоянно переписывать и документацию. Самое сложное лично для меня – изменять все скриншоты после выхода обновлений пользовательского интерфейса. Но все равно проводить обновления документации очень важно, потому что устаревшая документация автоматом говорит и об устаревшем коде.
Не думайте, что ваша документация закончена. Она не будет законченной никогда!
