Документация по продукту для профессионалов WordPress

Опубликовано: 2017-07-28

Документация по продукту обычно считается несущественной, так как вы можете срезать углы. Он не рассматривается как что-то, что может принести пользу клиенту, или как что-то, что может повлиять на ключевые области бизнеса, такие как доход и маркетинг. Конечно, как профессионалу WordPress вам не нужно писать документацию так же, как Atlassian или Cisco. Обычно, когда люди думают о «документации», они представляют себе изображения толстых печатных руководств пользователя, пронумерованных в алфавитном порядке на очень большой полке, которые никто никогда не читает.

Но это изменилось:

С появлением Agile и DevOps доставка ПО стала быстрее, а цикл разработки стал более динамичным. И в результате документация теперь отражает текущее состояние в новейшей версии, а не является чем-то статичным, написанным на бумаге навсегда. Документация интегрирована в цикл разработки и обновляется так же часто, как и программное обеспечение.

Почему профессионалы WordPress должны заботиться о документации продукта?

Полезная, актуальная документация не только облегчает жизнь вашим пользователям, но и добавляет уровень полировки, который становится маркетинговым активом, как никакой другой. И наоборот, плохая документация оказывает негативное влияние. Вы, вероятно, испытали это на себе: у вас была проблема, которую вы изо всех сил пытались найти в документации, и когда вы не нашли, вы в конечном итоге расстроились (и, вероятно, разозлились). Это только становится хуже, если вы платите за продукт.

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

  1. Вы обращаете внимание на детали.
  2. Вы достаточно заботитесь о своем клиенте, чтобы сделать все возможное.
  3. Вы прозрачны и уверены в своих проектных и технических решениях.

Майк Путербо, вице-президент по маркетингу в MindTouch, написал статью Mashable, в которой описал 5 причин, по которым ваша документация по продукту является маркетинговым активом. Он заключил следующее:

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

Теперь, когда у нас достаточно мотивации, мы будем:

  1. Изучите различные типы документации по продуктам, которые имеют отношение к WordPress.
  2. Обсудите потребности каждого типа документации и предложите действенный совет.
  3. Предложите некоторые начальные рекомендации о том, как вы можете планировать и совместно работать над документацией по продукту. Особенно, если вы работаете в агентстве WordPress.

Типы документации по продукту WordPress

Продукт WordPress — это не только плагины и темы. В этом разделе мы также обсудим онлайн-справку, REST API и любопытную вещь, называемую микроконтентом.

Плагины WordPress

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

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

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

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

Пользователи

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

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

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

Разработчики

Помимо следования лучшим практикам программного обеспечения и официальным стандартам кодирования PHP, вы должны сосредоточить свое внимание на следующих областях:

хуки плагинов

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

теги шаблона

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

опции

Параметры — это способ хранения определенных фрагментов информации в базе данных WordPress. Это делается с помощью функций add_option и get_options. В этом случае задокументируйте параметры, которые вы передаете этим функциям.

база данных

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

Темы WordPress

Есть две разные области, в которых вы можете создавать документацию для тем. Во-первых, это исходные файлы. Прокомментированные файлы CSS легче понять и прочитать, чем файлы без комментариев. Используйте такой инструмент, как css_doc, чтобы помочь вам. Это создает документацию в стиле JavaDoc, и ее можно опубликовать:

Другая область — руководства по стилю. Эти документы описывают, как должны выглядеть элементы и в каких случаях их нужно использовать. Они обеспечивают согласованность и облегчают совместную работу. Вы можете прочитать статью Hubspot «20 потрясающих примеров руководств по стилю бренда», так как она содержит множество замечательных примеров.

Опять же, не забудьте ознакомиться с официальными стандартами кодирования WordPress CSS.

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

Онлайн помощь

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

Барри Дж. Розенберг, автор книги Spring into Technical Writing, предлагает следующие советы по написанию хороших файлов справки:

Делайте каждый файл справки как можно короче. Предпочитайте нумерованные списки маркированным спискам. Не отвлекайтесь, не делайте сносок и не хотеть. Сосредоточьте каждый файл справки на одной отдельной задаче.

микроконтент

Микроконтент имеет два определения: первое — это такой контент, как заголовки и разделы, которые пользователи просматривают, чтобы понять суть конкретной статьи. Второй — это небольшие фрагменты контента, которые могут существовать сами по себе и использоваться для улучшения взаимодействия с пользователем. Один прекрасный пример, который мы имеем в виду, — это бит Slack «несколько человек печатают…». (хотя в Slack полно отлично написанного микроконтента).

Этот бит срабатывает, когда более 3 человек одновременно печатают на одном и том же канале. Вместо того, чтобы просто печатать список людей, которые в данный момент печатают, Slack берет эту скучную информацию и добавляет к ней немного забавы. Дискуссия становится действительно горячей, и это видно. Это отличный пример того, как документация по продукту (частью которой являются сообщения приложений, не так ли?) заставляет людей говорить о вас (и создавать веселые мемы, подобные приведенным выше).

ОТДЫХА API

Документирование API REST само по себе является отдельным искусством. Как и в любом техническом письме, вы должны стремиться к краткости, ясности и простоте определений. Поскольку REST API имеют свой собственный формат и сложности, вы можете сделать не хуже, чем изучить отличное руководство по документированию API от Тома Джонсона в его блоге I'd Better Be Writing.

Совместная работа и планирование документации

В конечном счете, документация должна быть частью дизайна продукта. Таким образом, вы должны подходить к этому как к дополнительному конвейеру в вашем программном цикле. Это означает использование репозиториев программного обеспечения для хранения самой последней версии документации, использование средств отслеживания ошибок/проблем для отслеживания задач и проблем, включение планирования проекта документации в свою дорожную карту и, что не менее важно, сотрудничество с другими людьми. Примерный план того, как начать, может быть следующим:

  1. Запишите все , что пользователь хотел бы знать, а также области, для которых вам нужно будет написать текст.
  2. Когда у вас все будет готово, сгруппируйте их по категориям и сформируйте названия документов.
  3. Напишите спецификацию для каждого документа с подробным описанием таких вещей, как заголовок, описание, целевая аудитория, СМИ (какая форма будет у документа), длина, сколько времени это займет и т. д.
  4. Добавьте оценки из спецификаций документации в планирование проекта.

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

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

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

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

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

Закрытие

Документация по продукту — это актив, который окупается в долгосрочной перспективе. Это придает ценность вашему клиенту. Он может быть даже настолько хорош, как, например, документация по API Stripe, что люди будут в восторге от него на форумах. Это создает взаимодействие и рекламирует ваш бренд и ваш продукт естественным и мощным способом. В сочетании с креативным микроконтентом достигается то, что имеет в виду Майк Путербо, когда говорит, что документация по продукту — это «секретное оружие маркетинга».