Полезные советы по документации WordPress-тем

Когда у вас имеется вопрос по функционированию тем WordPress, куда вы обычно обращаетесь за дополнительной информацией? Разработчики тем используют мириады разных методов по созданию документации, начиная от привязки doc-файлов и заканчивая ссылками на внешние ресурсы. Если вы уже создали тему и потратили определенное время на написание документации к ней, следующим вашим шагом будет сделать так, чтобы документацию можно было легко найти.

Если документацию будет тяжело обнаружить, пользователи пойдут на форумы, чтобы получить ответы на общие вопросы, которые, возможно, проще было бы кратко раскрыть в виде нескольких лаконичных заметок. Это заметно нагружает вашу службу поддержки. К тому же пользователям придется дольше настраивать тему, т.е. они не смогут пользоваться ей, пока не получат ответы на свои вопросы. Давайте исследуем некоторые способы, с помощью которых можно значительно упростить поиск документации.

Рекомендации по документированию тем WordPress.org

Темы, расположенные на WordPress.org, обычно имеют широкую аудиторию и отличаются наличием пользовательских руководств, которые призваны помочь такой масштабной пользовательской базе. Я поговорил с Чипом Беннеттом, который возглавляет команду обзора тем WordPress.org, чтобы узнать, как WordPress.org рекомендует документировать темы. Эти рекомендации окажутся полезными для вас даже в том случае, если вы документируете коммерческую тему или тему, которая расположена в стороннем хранилище.

Где лучше всего размещать документацию, чтобы пользователи ее заметили?

Беннетт приводит в качестве ответа комбинацию четырех разных методов:

1. readme.txt. Команда обзора тем рекомендует размещать всю документацию к темам в файле readme, который в идеале должен быть представлен в формате markdown.
2. Вкладка с контекстной справкой в панели администратора. Еще одно хорошее расположение для документации, которое зачастую обходится вниманием. Темы, включающие в себя страницу настроек, должны обязательно использовать богатый API Contextual Help.
3. Прилепленные записи на форуме. Для решения запросов в поддержку на форуме можно организовать прилепленные записи.
4. Ссылки на внешнюю документацию. Наконец, темы могут иметь объявленные Theme URI, которые будут использоваться для указания ссылки на ресурс с информацией/документацией по теме. Если какой-либо из встроенных методов документации покажется вам слишком ограниченным, то в таком случае вы можете применять ThemeURI (который может быть доменом, поддоменом, посадочной страницей или даже GitHub репозиторием/сайтом с документацией к теме).

Лучшие практики и советы по созданию документации к теме

Теперь, когда мы узнали, где поместить документацию к теме, самое время перейти к вопросу, что вообще лучше включать в документацию? Беннетт рекомендует начинать документацию с вопросов лицензирования и разъяснения всех нестандартных аспектов процесса установки темы.

«Лучшие практики по созданию документации темы включают в себя явное указание копирайта/лицензии для всех ресурсов, поставляемых вместе с темой, разъяснение любых необычных/нестандартных инструкций по установке темы, а также описание любой функциональности, которая не относится к ядру темы», отметил Беннетт. «Если касаться встроенной документации, то я советую разработчикам придерживаться стандарта phpDoc, который улучшает удобочитаемость, а также позволяет автоматизировать генерацию документации к теме».

Лучшие практики по созданию документации темы не такие строгие, поэтому вы можете выбирать для себя любой маршрут из четырех приведенных командой обзора тем.

«Поддерживается практически любой метод по созданию документации», говорит Чип. «Разработчики темы могут, конечно, поставлять справочные документы вместе со своими темами. Некоторые используют для этого readme.txt или readme.md, другие обращаются к HTML-файлам, третьи могут включать PDF», отметил Чип.

«Единственный минус такого подхода – отсутствие какого-либо стандартного/простого способа, позволяющего пользователю найти/использовать эти документы», предостерегает Беннетт. «Опять же, Contextual Help API может оказаться полезным (он может использоваться для вывода текста/HTML или ссылки на PDF-файл, к примеру), как и Theme URI».

Беннетт также отметил, что выбранный вами путь реализации опций темы будет напрямую влиять на то, сколько документации вам придется написать. «Другая важная практика заключается в том, чтобы создавать различные возможности на базе ядра WordPress, в результате чего вам придется меньше их документировать», говорит Чип.

«К примеру, применение функций ядра при реализации произвольных изображений в хэдере или произвольных фонов позволяет создать стандартный, интуитивный интерфейс для конечного пользователя. Точно так же, при реализации произвольной статичной главной страницы или произвольного шаблона записей блога грамотное применение иерархии шаблонов позволяет избежать потребности в документировании нестандартного использования этих особенностей».

Беннетт приводит несколько примеров тем, обладающих качественной документацией, которая всегда находится под рукой. Он разработал свою тему Oenology, которая обладает прекрасной документацией. Страница настроек Oenology использует контекстную справку для вывода дополнительной информации по параметрам, популярным вопросам, журналу изменений, поддержке и лицензировании.

Разработчики тем могут посмотреть Oenology, чтобы увидеть, как Беннетт добавил к этой теме всю документацию. Чип также рекомендует проверить тему Underscores, являющуюся образцом прекрасно документированной темы.

На WordPress.org появится больше возможностей по созданию документации

У авторов плагинов на WordPress.org есть возможность добавления дополнительной документации к вкладкам FAQ и Installation. Когда я разговаривал с Беннеттом, он отметил, что у авторов тем нет на данный момент такой возможности.

«Каталог тем гораздо более ограничен. Каталоги тем и плагинов, по существу, выглядят практически одинаково во фронтэнде, однако если залезать «под капот», то это два разных зверя», отметил он. «Инфраструктуры сильно отличаются. В будущем появятся некоторые изменения, которые позволят эмулировать ту же самую (или похожую) функциональность в каталоге тем, основанную на стандартном формате файла readme».

Команда обзора тем еще будет обсуждать то, как именно могут быть реализованы улучшения, однако пока непонятно, как вообще будут выглядеть эти изменения. А пока разработчики тем могут использовать рекомендации, описанные Беннеттом.

Чтобы создать хорошую документацию, нужно продумать стратегию ее предложения своим пользователям, когда им требуется помощь. Подсказки Чипа Беннетта полезны всем авторам тем WordPress, вне зависимости от того, создаете ли вы произвольную тему для клиента, продаете ли коммерческую тему или поддерживаете бесплатную тему на WordPress.org. Комбинация методов с readme.txt, встроенной документацией, контекстной справкой и сторонними документами, заданными в Theme URI, поможет вам создать качественную информационную базу.

Поработайте над созданием высококачественной документации, и вы снимете с себя бремя поддержки пользователей. Как автор темы WordPress.org, я бы предпочел потратить свое свободное время на обновление и разработку новых функций, нежели на решение одних и тех же вопросов со стороны пользователей. Использование ядра для реализации особенностей вкупе с обеспечением качественной документации – лучший способ освободить свое время для создания более интересного материала: красивых тем, которые обязательно полюбят пользователи.

Источник: wptavern.com