Документирование плагинов и тем WordPress

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

Почему важна документация?

Хранение обновленного набора документации о ваших проектах, активах или продуктах важно по многим причинам.

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

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

Наконец, документация придает вашим продуктам «отполированный» вид, и ваши клиенты будут любить вас еще больше.

5 принципов эффективной документации

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

Давайте пройдемся по 5 самым важным, чтобы вы могли писать эффективную документацию для своих продуктов!

• Лучше использовать меньше слов, чем вы обычно используете в своем письме: у каждого слова должна быть цель. Будьте прямолинейны и просты. Документация обычно требуется, когда человек попал в беду и хочет быстро найти решение. Например, предложение вроде «Неспособность уничтожить объект Q вызовет утечку памяти» предпочтительнее, чем «Неспособность уничтожить объект Q вызовет утечку памяти».
• Лучше использовать активный залог вместо пассивного: « Нажмите кнопку справа вверху» вместо «Кнопку справа вверху нужно нажать ». Использование активного залога устраняет любые двусмысленности в отношении того, кто что делает. Пассивный залог используется только тогда, когда вам нужно сосредоточиться на объекте, а не на теме (например, платформа Pressidium построена с учетом безопасности ) .
• Используйте описательный язык, когда вам нужно описать концепции, и императив, когда вам нужно описать пошаговую процедуру (например, учебные пособия).
• Используйте маркированные списки, когда вам нужно перечислить вещи, которые не имеют порядка, и нумерованные списки, когда важен порядок пунктов.
• Убедитесь, что вы проверили инструкции самостоятельно, прежде чем представлять их!

Документирование плагинов WordPress

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

Разместите свой сайт с Pressidium

60- ДНЕВНАЯ ГАРАНТИЯ ВОЗВРАТА ДЕНЕГ

ПОСМОТРЕТЬ НАШИ ПЛАНЫ

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

• Напишите убедительное и полезное описание, которое в конечном итоге заставит пользователя загрузить ваш плагин и посетить ваш сайт.
• Добавьте аннотированные скриншоты, объясняющие каждый элемент конфигурации вашего плагина, в дополнение к тем, которые показывают, как ваш плагин выглядит в браузере.
• Ставьте вопросы в FAQ, которые не банальны. Хороший способ обнаружить странные пограничные случаи — попросить друга, не разбирающегося в компьютерах, использовать ваш плагин.
• Иметь обновленный и хорошо написанный журнал изменений. Краткие и загадочные однострочники — это большой запрет и они показывают, что вы на самом деле не заботитесь о своих пользователях.
• Убедитесь, что код вашего плагина хорошо прокомментирован и соответствует лучшим практикам программного обеспечения и официальным стандартам кодирования.

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

Документирование тем WordPress

Документирование тем WordPress — это совсем другое дело. Самая распространенная проблема с темами WordPress заключается в том, что вы не знаете, какой раздел соответствует какому визуальному элементу. Не все свободно владеют CSS:

• Создайте иерархию всех разделов вашего CSS с соответствующими описаниями.
• Для каждого раздела добавьте аннотированный снимок экрана с подробным описанием каждой функции, а также небольшой пример. Не забывайте использовать активный залог и повелительное наклонение, когда показываете, как сделать что-то, что требует от пользователя следования инструкциям.
• Используйте такой инструмент, как css_doc, чтобы помочь вам. Это создает документацию в стиле JavaDoc и может быть опубликована.
• Иногда комментариев к коду недостаточно, и вам нужно создать документ «Руководство по стилю» для вашей темы CSS. Документы руководства по стилю описывают, как должны выглядеть элементы и в каких случаях их нужно использовать. Они обеспечивают согласованность и облегчают совместную работу. См. этот пример от Google.
• Используйте фреймворк CSS, например Blueprint CSS. Это поможет вам в разработке, предоставив вам набор инструментов, таких как настраиваемая сетка, работающая типографика по умолчанию, сброс CSS браузера и многое другое.
• Опять же, не забудьте ознакомиться с официальными стандартами кодирования WordPress CSS.