Подготовка технической документации *

Этот пост написан специально для одного человека, который спросил, в чате техписателей, как ему, техписателю, «прокачать структуру [технической документации] и силу слова».

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

Универсальный совет

В процессе работы над любым текстом, похожим на инструкцию, регулярно спрашивайте себя:

1. Какую задачу сейчас решает читатель?

2. Какая информация у читателя уже есть?

3. Какой информации читателю не хватает, чтобы решить задачу?

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

Notion уходит из РФ, удаляя все мои данные 9 сентября.

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

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

Notion сказал, что 9 сентября просто удалит под чистую все данные без возможности восстановления. Невероятно удобно и надежно и вызывает огромное доверие! Как у них на баннере написано "Write. Plan. Organize." и забыли добавить "... and we'll destroy it".

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

Теперь это все время стоит иметь в виду и не воспринимать "Облачный сервис" как что-то надежно. Удобное — да, а вот надежное оно лишь пока я для него буду оставаться удобным в ответ.

Уже лет 10 про роль техписателей активно рассказывают сами техписатели. Однако за последнюю пару месяцев я лично несколько раз слышала вариации на тему: «у нас ТЗ пишут аналитики, значит и на пользовательскую доку аналитика наймём» или «ищем техписателя, который будет писать нам ТЗ». Но добило меня: «я думал, что аналитик — это следующая стадия развития техписателя».

Технический писатель — это тот, кто пишет техническую документацию?

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

Технический писатель — это тот, кто пишет технические задания?

Нет. Технический писатель создает инструкции к сложным объектам.

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

Я в чём‑то сложном разобралась, научилась этой штукой пользоваться, и объяснила другому так, чтобы он сказал — спасибо, я всё понял. Если штуки ещё не существует, но мне уже надо написать, как с ней работать, то я не техписатель, а, например, менеджер продукта;)

Так, а что техписатель делает на работе?

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

На прошедшей недавно (не)конференции Yandex Open Source Jam Юрий Пузыня подробно рассказал об опенсорс‑платформе для работы с документацией Diplodoc — и за 40 минут вместе с участниками собрал готовую документацию (и даже осталось немного времени на лендинг, собранный на Gravity UI).

Чтобы повторить то же самое, а также узнать, что вообще можно сделать на Diplodoc, смотрите запись выступления. Всё, что вам понадобится для работы, команда также собрала в отдельной документации.

Пробуйте, задавайте вопросы, делитесь впечатлениями — например, на GitHub или в чате сообщества в Telegram.

Про процесс ДХП (документальный ход проекта)

Исторически в агентствах за документальным ходом проектов следят менеджеры. У нас тоже всегда было так. Однако проекты росли и усложнялись, а параллельно росла сложность документальных отношений с заказчиками, вследствие чего РП всё чаще начинали забивать на тщательный контроль документов и возникла острая необходимость в разделении труда.

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

Администратор проекта закреплен за несколькими проектными офисами и ведёт до 10 активных клиентов. По итогу этой работы проектной команде и руководству раз в месяц уходят письма с документальным статусом проекта, выглядят они вот так:

Таким образом мы:

• контролируем все документальные риски и узнаем о них заблаговременно;

• снижаем риски непреднамеренного нарушения условий договора;

• получаем дополнительный источник информации о потенциальном срыве сроков проекта;

• разгружаем руководителей проектов;

• передаем весь документальный процесс специалистам с опытом в этой сфере и с фокусом на эту составляющую;

• контролируем и уменьшаем объем работы без подписанных документов.

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

Приходит потенциальный клиент к разработчику…

— Мне бы сайт разработать! Можете сказать, сколько это будет стоить?
— А проектная документация у вас есть?
— Не-а.
— Она нужна для оценки. Попробуйте сходить к проектировщику интерфейсов. Возвращайтесь с проектной документацией — и я оценю разработку.

И клиент идёт к проектировщику интерфейсов. Например, ко мне.

— Мне бы сайт спроектировать! Можете сказать, сколько это будет стоить?
— А задание на проектирование у вас есть?
— Не-а. Только не говорите, что опять надо к кому-то идти?!
— Нет. Давайте с вами созвонимся такого-то числа во столько-то — и я за час соберу у вас все необходимые сведения для составления этого задания. Дальше вы проверите, нигде ли я не ошибся — и если всё ок, то я смогу оценить проектирование.

Вот примерно так я обычно и создаю документы под названием «Функциональные требования» (ФТ). По ним я могу оценить объём работ по проектированию. Вот вам видеоролик, в котором показываю пример такого документа и рассказываю о некоторых нюансах его подготовки.

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

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

There is a secret that needs to be understood in order to write good software documentation: there isn’t one thing called documentation, there are four.

They are: tutorials, how-to guides, technical reference and explanation. They represent four different purposes or functions, and require four different approaches to their creation. Understanding the implications of this will help improve most documentation - often immensely.

https://documentation.divio.com

Эксперт Джон Джаго назвал два проекта с открытым исходным кодом, у которых разработчиками собрана и представлена исключительная техническая документация, включая высокую детализацию кода и архитектуры. Это esbuild и Redis.

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

Преимущества хорошей документации:

• экономия времени на работы с кодом, особенно если работаете командно, не нужно дополнительно объяснять всю кодовую базу каждому разработчику;

• такой проект с открытым исходным кодом с большей вероятностью получит поддержку со стороны и, следовательно, продолжит своё существование даже после того, как автор больше не сможет его поддерживать;

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

• приложение или библиотеку смогут использовать больше людей, поскольку меньшему количеству из них придётся во всем разбираться самостоятельно;

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

5 полезных расширений VScode для работы с документацией

1. Draw.io Integration
   
   Хорошо подходит для работы со сложными диаграммами: сперва можно создать диаграмму в десктопной версии Draw.io, а потом доработать ее в VScode с помощью расширения Draw.io Integration.

2. Quarto
   
   Quarto — крутая штука для работы с документацией под R, Python, Julia и Observable. Расширение Quarto для VScode поможет редактировать и рендерить QMD-файлы. В нем есть режим предварительного просмотра, который позволяет менять код документа и одновременно просматривать результат.

3. Jupyter
   
   Jupyter — один из самых популярных фреймворков для создания заметок, особенно в Python. Кстати, Jupyter классно работает вместе с документацией Quarto для Python. Расширение VScode Jupyter интегрирует заметки Jupyter в редактор VScode и поддерживает ipynb-файлы.

4. Markdown All in One
   
   С расширением Markdown All in One удобно редактировать документацию в формате Markdown. Оно располагает два окна рядом: редактор кода и тут же результат.

5. Mermaid
   
   Mermaid особенно полезен, если вам нужно создать структуру кодовой базы или динамическую диаграмму. В VScode есть два расширения для работы с файлами Mermaid — Mermaid Preview и Markdown Preview Mermaid Support.

Этот топ расширений составил автор этой статьи, а ее перевод читайте у нас в блоге.

Для решения одной задачи мне потребовалось найти закрепленное в стандартах определение понятия "информация". Из тех, что я нашел, мне наиболее понравилось:

знания относительно фактов, событий, вещей, идей и понятий, которые в определённом контексте имеют конкретный смысл.

Если верить Википедии, статье на Хабре и статье в научном журнале, это определение дано в ISO/IEC 2382:2015 «Информационные технологии. Словарь».

В оригинале этого стандарта я, действительно, вижу похожее определение информации:

knowledge concerning objects, such as facts, events, things, processes, or ideas, including concepts, that within a certain context has a particular meaning

Но, в адаптации этого стандарта под ГОСТ, я обнаружил только трактовку в контексте каких-то финансовых учреждений:

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

Притом, что иные определения в этом ГОСТ даны в общем контексте и довольно близко по смыслу. Кто-нибудь понимает, что это за нафиг и откуда вылезли финансовые учреждения?