Unlimited WordPress themes, graphics, videos & courses! Unlimited asset downloads! From $16.50/m
Advertisement
  1. Code
  2. WordPress
Code

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

by
Difficulty:IntermediateLength:MediumLanguages:
This post is part of a series called How Theme Frameworks Actually Work.
Releasing your WordPress Theme Framework

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Заключение

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

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

Advertisement
Advertisement
Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.