Учебник по написанию хорошей документации

Этот пост был предоставлен приглашенным автором Джеффом Мэтсоном. Джефф — руководитель отдела документации GravityForms. Он является создателем плагина Heartbeat Control для WordPress и фанатом 90-х.

Часто документация является самой недооцененной частью процесса разработки. Когда мы смотрим на рок-звезд в сообществе WordPress, мы обычно смотрим на разработчиков, дизайнеров и маркетологов. Мало что известно о составителях документации, которые проливали кровь, пот и слезы, чтобы все работало гладко.

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

Хорошая документация — больше, чем слова

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

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

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

Документация имеет большее влияние, чем вы думаете

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

Давайте взглянем на ваш самый распространенный тикет в службу поддержки. Если бы вы лучше задокументировали эту проблему, исчезли бы эти тикеты полностью? Возможно нет. Будете ли вы получать меньше обращений по этой проблеме, а также повысите свою производительность или производительность вашего агента поддержки? Я гарантирую это. Я думаю, мы все могли бы использовать меньше заявок в службу поддержки.

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

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

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

Как вы можете написать лучшую документацию?

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

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

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

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

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

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

Искусство написания лучшей документации

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

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

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

Чему мы научились

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

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

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