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

На прошедшей недавно (не)конференции 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

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

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

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