Эта статья будет полезна тем, кто отчаянно нуждается в документации, но не обладает ресурсами и навыками технического писателя. Например, менеджерам, разработчикам или тестировщикам, небольшим стартапам, проектам внутри компаний или командам, которые хотят облегчить погружение новых сотрудников в проект и процессы.
Меня зовут Люсьена Мирославская, я работаю техническим писателем в Wildberries третий год. На протяжении развития моей карьеры в IT, а это более пяти лет суммарно в разных компаниях, я часто сталкиваюсь с проблемой недостаточности документации. Её или нет, или она неактуальная, неполная, неверная, да и несистематизированная, а иногда просто непонятная. Я не волшебник, поэтому не смогу вместить весь свой опыт в одну статью, но точно задам направление для ориентира и помогу, как минимум, создать черновик документации.
Так как написать первую статью, если не знаешь, с чего начать и что делать?
Всё просто!
Первое. Определите объект документации – какое решение или функциональную возможность продукта вы хотите описать.
Возможно, речь пойдет о техническом решении, которое нужно реализовать или оно уже реализовано и работает. Возможно, вы хотите описать микросервисную архитектуру, устройство определенного сервиса или, скажем, базы данных. Может, речь пойдет о подключении или настройке какого-то компонента, системы? Об интеграции вашего решения в систему партнеров? Сформулируйте коротко и ясно одно предложение. Используйте в начале слова: «инструкция», «архитектура», «спецификация» или такие: «описание», «формат», «процесс». Например, «Инструкция для интеграции с порталом «Классное решение» по API v2.1» или «Архитектура системы отправки смс». Теперь у вас есть название статьи и понимание, на чем нужно сфокусироваться, о чем вы будете писать.
Второе. Определите, какую проблему решает ваша статья.
Ознакомившись с ней, читатель получит просто информацию об устройстве или существовании чего-то? Или он найдет описание параметров запроса? Может, получит инструкцию по настройке или использованию какого-то продукта? Отлично! Запишите себе ответ на эти вопросы.
Теперь у вас есть понимание, в каком ключе вести описание, и первое предложение. Например, «Чтобы интегрировать решение в ваш проект, выполните такие-то шаги…» или «Архитектура информационной системы такой-то состоит из следующих компонентов…». Тут можно вернуться к первому пункту и убедиться, что из названия прямо или косвенно можно понять, о чем будет статья и в каком формате ее нужно писать.
Третье. Продумайте структуру статьи.
Это поможет вам сделать статью легкой для восприятия и усвоения информации, а читателю ориентироваться в ней и искать важные нюансы. Это главный пункт, который является залогом успеха. Запишите тезисно, о чем и в какой последовательности пойдет речь.
Теперь у вас есть названия разделов или пунктов. Продолжим?
Четвертое. Наполните каждый пункт содержательной частью.
Помните о том, что хорошая документация – точно бусы. Раздел за разделом нанизываются на леску, сочетаются между собой и перекликаются. Каждый является самостоятельной и законченной единицей, но вместе они составляют одну композицию. В случае инструкции, каждый раздел – это шаг. Если вы описываете систему – устройство ее компонента. Для спецификации – метод и его параметры.
Пятое. Не бойтесь тавтологии.
В общем и целом повторение – мать учения, а в документации повторение – гарантия однозначности и правильной трактовки. Не стремитесь одну сущность называть разными терминами, отчаянно избегая повтора. Вы пишите не художественное произведение. Вы делитесь ценными знаниями. Читатель не должен задаваться вопросом: «термин 1» и «термин 2» это одна сущность или две разные? Хорошая документация дает ответы на вопросы, а не вызывает новые.
Почти готово! Еще несколько важных моментов:
1. Следите за объемом информации. Если ее много, читать вряд ли будут внимательно или полностью. Практика показывает, что длинные тексты мало кому нравится читать. Длинные и скучные тексты редко дочитывают до конца.
2. Не распыляйте внимание на детали. Одного-двух предложений будет достаточно. Напишите лучше отдельную статью, если это важный и сложный момент, требующий особого внимания. В противном случае у читателя может возникнуть вполне резонный вопрос: «что я вообще прочитал только что?» или «так о чем статья?»
3. Не повторяйте одну и ту же мысль несколько раз, но в разных формулировках и местах. Это раздражает и путает. Старайтесь донести свою мысль с первого раза, используя точные формулировки. Не стоит разжевывать одну мысль несколько раз, если вы понимаете, о чем я ;-).
4. Функциональность, а не функционал! Это Важно. Дьявол кроется в деталях, а Бог – в мелочах. Функционал – это математический термин, а именно, функция, заданная на произвольном множестве и имеющая числовую область значений (обычно множество вещественных чисел или комплексных чисел). Поэтому, если описываете возможности программы или информационной системы, пишите «функциональность» или «функциональные возможности».
5. Лучшее решение – порядок слов прямой! Не используйте инверсию или другие литературные приемы в вашем тексте. Вы все-таки пишите документацию, а не поэму. Слишком творческий подход может вызвать недоумение у читателя.
6. Используйте ссылки на другие статьи, чтобы не перегружать информацией свою. Но тут нужно быть внимательным и оформлять ссылки правильно. Не стоит добавлять их так: https://habr.com/ru/companies/wildberries/articles/.
7. Смело добавляйте схемы, картинки и скриншоты для визуализации. Но не переборщите. Лучшее – враг хорошего. Помните, что картинка ради картинки или схема для красоты – могут изменить смысловую нагрузку и стать мусором в статье.
Готово. Вы великолепны!
Когда напишите статью, похвалите себя. Нет, открывать дверь с ноги и требовать у менеджера платить вам еще и ставку технического писателя рано. Однако, плюсик в карму поставить можно и даже добавить строчку в резюме «писал документацию для проекта» тоже.
Помните, что данная статья задаёт только направление и помогает начать, а не гарантирует, что вы с первого раза напишите идеальную документацию. Любой разработчик может прочитать книгу «Чистый код» или «Идеальный программист», но это не значит, что после прочтения он сразу будет писать крутой и правильно работающий код. Пробуйте и практикуйтесь! Сохраняйте эту статью в избранное и возвращайтесь к отдельным советам по мере необходимости. Разработка хорошей документации – это трудоемкий творческий процесс, требующий определенных ресурсов, знаний не только в предметной области, но и умения грамотно облечь мысли в текст, затем правильно его оформить и разместить.
Это была вводная статья о документации. Что ещё вам было бы интересно узнать о процессах или практиках создания технической документации? Делитесь в комментариях!
