Как стать автором
Обновить

Комментарии 16

Есть ещё один важный пункт — донести до руководства и заказчика, что документация, а тем более хорошая — это отдельная полноценная работа, она не делается «на сдачу» в перерывах во время основной работы, и в зависимости от сложности и подробности может занимать и под половину от производственного бюджета проекта.
С другой стороны, если автор статьи – руководитель отдела технической документации, то где-то, выходит, есть аж целый отдел технической документации. Вселяет надежду, что техписы ещё не вымерли, как динозавры.
Не вымерли :) Plesk — достаточно сложный продукт, и им пользуется много людей с очень различным багажом знаний. Наши клиенты (и клиенты наших клиентов) решают с его помощью реальные бизнес-задачи, и когда у них что-то не получается, выхода три — спросить у соседа, написать в поддержку, или загуглить.

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

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

Приходится писать много разных текстов. Есть заказы и написание документации. Надеялся, что попалась полезная статья. Жаль, но оказалось, что это набор деклараций без наполнения смыслом. Это примерно так, когда учат писать заголовки к статьям. Все сводится к лозунгу – товарищи, пишите цепляющие заголовки! Жаль, что у автора не получилось.

Спасибо за обратную связь. А как выглядит «наполнение смыслом» в вашем представлении? Можете развернуть эту мысль?

Что такое “хорошая документация”?

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

Минимум нужно рассмотреть два вида документации. Это документация в бумажном или электронном виде. Как сделать удобную документацию на бумажном носителе и как организовать документацию в электронном виде.

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

Хорошую документацию легко найти

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

Какая разница техническому писателю, по каким запросам ищут вашу документацию? Может быть, это важно для разработчика ТЗ, специалиста по SEO?

Хорошую документацию легко понять

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

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

Везде сейчас учат, избегайте канцелярита, простые предложения, короткие абзацы.

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

Хорошая документация описывает сценарии

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

Классический подход в написании документации – это о чем? Что вы имеете в виду, используя данный термин. Скорее всего, у меня другое понимание этого термина, а других людей свое.

Для меня описание сценариев – это написание инструкции, которая может быть составной частью документации.

Хорошая документация самодостаточна

Да, правильный посыл.

Но как часто вы читаете справочник с первой страницы? А документация ближе к справочнику, а не к художественной или публицистической литературе.

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

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

На этом закончу…  Хотя, эту тему можно развивать бесконечно долго.

Заключение

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

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

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

Ок, это про контекст. Я исходил из предпосылок, казавшихся мне очевидными (чертово проклятие знания). С моей точки зрения, бумажная документация — атавизм, и в 21 веке пора перестать убивать деревья ради чего-то, чем никто не пользуется. Не помню, когда я последний раз брал в руки бумажный мануал — они отправляются сразу в переработку.
Документация может быть в сети, но в виде PDF файлов, а может быть выполнена в виде раздела сайта с несколькими видами поиска.

То же, что и выше. Почти нет разумных причин делать документацию в .pdf кроме «мы всегда так делали». Когда-то человечество хранило информацию на пергаменте, бересте, восковых табличках. Для нужд документации .pdf подходит не лучше. Мы все всегда онлайн, у каждого есть смартфон в кармане. Если эти условия не верны — пользователь в меньшинстве, и городить отдельное решение для него не кост-эффективно. Plesk перестал публиковать доки в .pdf шесть лет назад, количество поступивших на это жалоб — ноль.
Зачем писателю знать, что пользователи вашего продукта приходят на сайт с документацией из органического трафика? Что он может из этой информации почерпнуть?

То, как в реальности ведут себя люди, для которых он работает.
Какая разница техническому писателю, по каким запросам ищут вашу документацию? Может быть, это важно для разработчика ТЗ, специалиста по SEO?

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

В моем контексте эти вопросы обсуждаются с ответственным ПМом. О важности говорить на языке пользователя я упомянул.
Не так давно везде учили, что текст для интернета не должен превышать 500 знаков, читатель не осилит длинный текст. Жизнь показала, что важна не длина текста, а его содержание. Так и с документацией. Главное, чтобы пользователь с помощью документации мог легко найти решение своей проблемы или научиться выполнять нужные действия.

Это про Make it as short as it can be and no shorter. Важно уметь отрезать весь жир, но при этом не задеть мускулы или, тем более, кости.
Классический подход в написании документации – это о чем? Что вы имеете в виду, используя данный термин. Скорее всего, у меня другое понимание этого термина, а других людей свое.

Да, согласен, мой косяк. Ввел термин, не объяснив значения. Думал, что у каждого перед глазами сразу возникнет картинка типичной инструкции. «Классический подход» — в моем понимании — это иллюстрация с выносками + попунктное объяснение того, что каждый описываемый объект делает. Кнопка А. Рукоятка Б. Индикатор В.

Чтобы понять, в чем проблема такого подхода, опишу, как мы представляем человека, пользующегося документацией (для нас это аксиома). Он пытался решить проблему сам, но не смог, и теперь ищет решение и хочет затратить на это минимум времени и усилий. Он не хочет получить всеобъемлющие знания о предмете, его интересует один какой-то сценарий («Хочу постирать грязное белье»).

«Классическая» документация перегружает его не связанной информацией. Вот кнопка А. Она делает то-то. Мне нужно ее нажимать или нет? Я должен принять это решение самостоятельно. Боже упаси, если для того, чтобы стиральная машинка заработала, мне нужно открыть кран с водой, потому что он в шкафчике под раковиной и о нем рассказывается вообще на другой странице. В то время как сценарная документация сфокусирована как лазер. Делай раз. Делай два. Успех.
Но как часто вы читаете справочник с первой страницы? А документация ближе к справочнику, а не к художественной или публицистической литературе.

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

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

Это безусловно. Доку о том, как настроить почтовый клиент мы будем писать совсем по-другому, нежели доку о том, как работать с расширением для Докера. Так как предполагаемый уровень технических компетенций у ЦА для этих сценариев очень разнится.
Я так и не знаю, как написать хорошую документацию. Хорошая документация понятие растяжимое и ее качество в большей степени зависит от подходов, которые используются при создании. Для меня важно создать текст, который полностью удовлетворит все запросы заказчика.

В защиту своей статьи могу сказать следующее: в нерабочее время я — простой потребитель товаров и услуг, как и все мы. И я часто сталкиваюсь с плохой документацией (у меня была проблема, документация не помогла ее решить или я ее вообще не нашел). И без исключения вся плохая документация нарушает какое-либо из правил, перечисленных в статье (зачастую почти все из них). И наоборот, хорошая документация (которая помогла самостоятельно выйти из затруднения) неизменно им соответствует. Я такое замечаю — «о, ништяк, все сценарненько и по делу, хороший десижен сапорт, и не устарело, все работает. Пять баллов, коллега». Надеюсь, хоть что-то вы из нее сможете почерпнуть :) В любом случае, спасибо за потраченное время и за комментарии.
Забавно что статья о том как писать хорошую документацию, по ней же самой является плохой документаций
Ну так это же не документация (во всяком случае, в моем представлении), это статья-референс, набор лучших практик :)

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

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

Не-не-не. Забывать об этом никак нельзя. Но это уже про DocOps, про то, что документация — это не результат, а процесс, про то, что обратная связь рулит и ее нужно собирать, процессить, и вносить на ее основе изменения. Мы все это делаем. Но это уже тема для отдельной статьи :)
Нет, это про методологию в целом.
Либо Waterfall, и тогда надо выбрать инструмент, составить оглавление, написать документацию по каждому пункту, добавить глоссарий, проверить на непротиворечивость и связность, передать на поддержку.
Либо Agile, тогда документация делается сначала MVP, потом совершенствуется по мере потребности, а потребности тщательно отслеживаются и оцениваются.
Возьму на заметку. Как раз у нас в компании поняли что написание и поддержка документации это тоже работа. Но, мы уже год не можем выбрать единственную платформу которая подходила бы для

1. Написания сухой документации аля отправьте это — получите то
2. Описания юз кейсов и различных флоу
3. Публикацию бест практис в виде статей
4. Хороший поиск
5. Вставка и форматирование кода
6. Можно было бы разделять внутреннюю документации дл] инженеров от публичной которую мы даем партнерам.

Сейчас у нас документация разбросана по гиту (wiki), wix и собственный статический сайт где нужно коммитить изменения в репо и деплоить.

Может кто посоветует чего?

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

Поглядите в сторону www.zendesk.com может быть? У нас в нем техническая поддержка разрабатывает и хранит базу знаний, на первый взгляд, кажется, инструмент удовлетворяет всем вашим требованиям.

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


Статью можно сократить (я использовал основные заголовки).


Советы по созданию инструкции


  • Инструкцию легко найти
  • Инструкцию легко понять
  • Инструкция описывает сценарии
  • Инструкция самодостаточна
  • Инструкция достоверна
  • Инструкция пишется для определенной аудитории
  • Инструкция оказывает поддержку

Но это была бы уже не статья, а checklist создания инструкции.

Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.