Написание Документации для Фреймворка Вашей WordPress Темы

Russian (Pусский) translation by Narine Hovhannisyan (you can also view the original English article)

Итак, теперь у вас есть фреймворк WordPress темы. Поздравляю! Старания, которые вы вложили в его разработку, себя окупят и сделают процесс разработки гладким, более рациональным и эффективным.

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

Я расскажу о следующих вариантах:

Комментирование
Создание файла readme
Использование автоматизированных средств документации
Создание вики-страницы
Создание сайта
Создание руководств или видео записей

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

Написание Качественных Комментариев

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

Представьте, что сделали сайт для клиента, используя ваш фреймворк. Спустя два года, в 5:30 в пятницу на сайте возникает проблема. Хорошие комментарии внесут разницу между быстрым исправлением ошибки, проведнием выходных дома и рассмотрением сотен строк кода и пропуском пятничного вечера.

Вот несколько заметок для хороших комментариев:

Используйте комментарии вначале вашего файла для объяснения того, что делает этот файл. Например, в файлы-шаблоны включите заметку о том, какие данные отображает этот файл и об изменениях, внесенных вами в цикл или в другую часть файла; в файлах плагина добавьте заметку о его функциональности. Например, комментарии внизу говорят пользователям название файла-шаблона, о том, что он делает, частью какой темы он является (@package), и начиная с какой версии он использовался (@since). Вы должны использовать аналогичную систему для файлов плагина.

/**
 * Template Name:sidebar-products.php
 *
 * The include file used for the sidebar on pages using the single-product.php template. Displays a gallery of product images (omitting the featured image which is displayed in the content).
 *
 * @package wpptl-theme-framework
 * @since version 1.0
 */

Используйте комментарии для демаркации секций вашего кода не только в таблицах стиля, но и в файлах-шаблонах и в файле функций вашей темы.
Комментируйте все нестандартное.
Комментируйте все то, над чем вы долго работали — используйте детализированные комментарии, так что когда вы вернетесь к коду, вам не нужно будет над ним снова думать.
Комментируйте все то, над чем будет работать кто-то другой — например, если файлы вашей темы содержат в себе скрипты, которые будет изменять другой разработчик, добавьте комментарии, объясняющие, где они применяются на сайте.
Используйте формулировку в ваших комментариях, чтобы позже вы смогли найти с помощью поиска — так что не сокращайте и используйте термины, которые другие пользователи смогут понять.
Всякий раз, когда вы закомментируете некоторый код, добавьте комментарий для вас с указанием причины. Таким образом, если вы забыли удалить код после того, как вы закончили, или захотите добавить его обратно в будущем, вы будете в курсе происходящего.
Если сомневаетесь, добавьте комментарий!

Создание Файла Readme

Файл readme.txt является следующим уровнем после комментариев. Это отдельный файл, который вы включаете в вашу тему, содержащий информацию о ней.

Код, сопроваждающий эту серию, содержит в себе простой файл readme.txt:

1	Создание фреймворка вашей WordPress темы
2
3	Эта тема поддерживает 6-ую часть этой серии для wptutsplus.
4
5	Тема включает в себя следующие файлы-шаблоны:
6	archive.php
7	index.php
8	page.php - for static pages
9	page-full-width.php
10	archive.php - for archive pages
11	header.php
12	sidebar.php
13	footer.php
14	loop.php
15	loop-single.php
16	loop-page.php
17	functions.php
18
19	Тема поддерживает популярные изображения, меню и виджеты и использует их следующим образом:
20
21	Популярные изображения:
22	Они отображаются в шаблонах archive и index, если они есть, используя средний размер.
23
24	Меню:
25	Меню по умолчанию находится в header.php и использует админ-панель Menus
26
27	Дизайн
28	Тема использует Объектно-ориентированный CSS (OOCSS). Следующие классы созданы для макета и вы можете использовать их в ваших страницах и постах.
29	Они адаптивны, так что будут уменьшаться на маленьких экранах (например, класс .half будет в полную ширину на мобильных)
30	.full-width
31	.three-quarters
32	.two-thirds
33	.half
34	.third
35	.quarter
36
37	Хуки
38	Существует 7 хуков-действий:
39	Над header
40	Внутри header
41	До контента
42	После контента
43	В боковой панели
44	В footer
45	После footer
46
47	Существует 3 хука-фильтра:
48	1 в header
49	2 в footer
50
51
52	Виджет-Зоны
53	Существует шесть виджет-зон, все добавлены с помощью файла widgets.php:
54	- одна в header
55	- одна в боковой панели
56	- четыре в footer

Если вы хотите сделать ваш файл readme более простым в употреблении, то вы наверняка захотите создать readme.html файл, который откроется в браузере пользователя. Вы можете использовать CSS для создания вашего уникального файла readme и сделать его более легким для прочтения.

Если вы хотите выпустить ваш фреймворк через репозиторий WordPress тем, вы должны будете предоставить файл readme.txt как минимум в форме документации. Я расскажу об этом в последнем уроке этой серии, в выпуске фреймворка вашей темы.

Использование Автоматизированных Средств Документации

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

Многие из них включают использование специальных тегов или синтакса для того, чтобы система могла определить место создания документации. Примеры включают:

PHPDocumentor что специфично для PHP
APIgen также специфично для PHP
Doxygen
Groc

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

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

Создание Вики-Страницы или Сайта

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

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

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

Если ваш фреймворк абсолютно бесплатный, вы можете создать бесплатный сайт с документацией, как в случае с фреймворкрм Wonderflux:

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

Создание Руководств или Видео Записей

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

Фреймворк Genesis имеет целый ряд учебных пособий для пользователей, которые доступны только платным подписчикам:

Мой собственный фреймворк Edupress имеет ряд учебных видео, которые я создала для того, чтобы помочь пользователям с различной степенью опыта работы с компьютером и небольшим опытом использования WordPress:

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

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

Заключение

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

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