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

Шаблон записи о принятии архитектурного решения

# Идентификатор и заговолок

Утверждение о принятом решении.

# Статус

Черновик\Утверждено\Заменено на ADR-XXX

# Контекст

Почему решение необходимо. Предположения, ограничения, мотиваторы принятия решения.

# Критерий оценки

Какие приоритеты в принятии решения? Какие из параметров и характеристик системы рассматриваются или используются в принятии этого решения. Какие мотиваторы и ограничения использовались при принятии решения?

# Доступные варианты

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

# Решение

Сделанный выбор и аргументация в его пользу.

# Последствия

Положительные и отрицательные последствия принятого решения.

# Консультации

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

Простой, быстрый и бесплатный тест на профориентацию.

1. Кто вызывает у вас зависть? Почему? Что он—она делает? Что именно вас впечатляет в результатах?

2. Что это за роль в экономике: сотрудник в найме, учёный на грантах, волонтёр или вообще целый бизнес?

3. Когда вы почувствовали укол зависти, в каком контексте находился ваш предмет зависти? Выступал на конференции или что-то ещё? Сколько процентов от общего времени занимает эта активность, как думаете?

4. Если выяснится, что для результата, который вызвал у вас зависть, нужно много работать и 80% времени делать рутинные, неинтересные вещи, ваша зависть уменьшится или не сильно?

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

Инфостиль разрешает вам писать просто и ясно. И не поощряет вас делать вид, что вы умнее, чем вы есть на самом деле.

Всё. Больше инфостиль ни в чём не виноват. Все проблемы, все неудачи — из-за вас, а не из-за инфостиля.

Привет! Сегодня мы хотим представить программу для контрибьюторов Diplodoc — опенсорс-платформы Яндекса для создания документации в формате Docs as Code. Это ваш шанс внести значимый вклад в развитие платформы и получить классные призы за участие.

Мы предлагаем

Мы создали специальную подборку задач, которые вы можете решать, чтобы помочь нам улучшить платформу. Задачи доступны на разных уровнях сложности: easy, medium и hard. Это отличная возможность проявить себя, внести свой вклад в проект и получить заслуженные награды.

Вы получаете

За решение лёгких и средних задач мы подготовили стильный мерч Diplodoc. А за сложные задачи вы вдобавок получите промокод на использование ресурсов Yandex Cloud.

FAQ

Как выбрать задачу?

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

Как отправить решение?

Подготовьте PR с вашим решением. Наша команда проверит его. Если в итоге он будет принят, вы получите подарок.

Сколько задачек можно решить?

Сколько угодно, однако приз вы получите только за одно решение.

До какого числа действует программа?

Программа активна до конца января. Мы будем добавлять задачи, так что следите за обновлениями в нашем чате в Telegram!

Не упустите возможность внести свой вклад в будущее Diplodoc!

Используем PlantUML не по назначению: рисуем маппинг данных с помощью диаграммы класса

Когда у вас docs as code, хочется, чтобы все было прямо по «докс экс кодовски», в частности, чтобы диаграммы и схемы тоже рисовались кодом.

Ниже — пример того, как можно изображать маппинг данных с помощью диаграммы классов. Достаточно использовать несколько ухищрений и «костылей», чтобы получать довольно неплохие результаты.

Вот так выглядит код (если нужны пояснения, обращайтесь):

@startuml

hide circle
left to right direction

class Structure_1 {
  field_1
  --
  field_2
  --
  field_3
}

class Structure_2 {
  field_1
  --
  field_2
  --
  field_3
}

package transform <<Rectangle>> #yellow {
  
}

package "addition data" <<Rectangle>> #purple {
  
}

package "data transform" <<Rectangle>> #blue {
  
}

Structure_1::1 -down[#white]-> transform
Structure_1::1 -down-> transform
Structure_1::1 -down[#white]-> transform

transform -down-> Structure_2::1

Structure_1::2 -> Structure_2::2

Structure_1::3 -down-> "data transform"

"data transform" -down-> Structure_2::3

"addition data" -down-> 

А так — результат (маппинг данных):

Какие нюансы нужно учесть:

1. Активно «играйте» связями: они помогают двигать объекты на диаграмме.

2. Используйте невидимые элементы и связи.

Сначала это кажется сложно. Но позже, когда освоишь ухищрения и «костыли», рисовать настоящие шедевры. И тогда у час будет полнейший docs as code.

Похожее можно рисовать и в graphviz, но там синтаксис потяжелее будет. Как? Могу показать.

Стиль — это стиль. Если воспринимать моду на термины и графические знаки именно как моду, предмет перестаёт быть таким уж холиварным. Не нужно спорить. Нужно просто всё время спрашивать себя, на кого я хочу быть похож. На свою жилконтору или на DigitalOcean. Главное не оказаться охранником из книги Пелевина:

— Принято так, — сказал охранник, снимая со стены один из фонарей и протягивая его Сердюку. — Вы ведь галстук тоже не от холода носите.

Вот примеры сложных выборов :)

Вначале было слово e‑mail, потом вариант email (без дефиса) был принят в словари страны происхождения и попал во все англоязычные гайды. То есть был принят большинством. Сейчас дело не в том, нравится вам лично этот вариант или не нравится, а в том, какую одежду вы хотите носить — ту, что была модной десять лет назад, или ту, которую сейчас носит ваша любимая компания.

Ещё пример, тоже про большинство. «Кавычки‑ёлочки». Хорошо сочетаются с кириллическим алфавитом. Носят примерно с 15 века. Но в 21 веке всем внезапно стало лень и теперь я очень часто вижу программистские кавычки в текстах, а не в коде. Мне ёлочки нравятся. Жаль, если их таки вытеснят программистские кавычки. Потому что особого практического смысла это иметь не будет. А красоту мы потеряем.

Была тут относительно "давно" статья от меня.. Прокачивает КД на новый уровень..

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

По этому поводу, собственно опрос..

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

Нужна вторая часть безумных предложений? Или нет?

P.s.. прошу либо голосовать за пост, либо в комментариях оставлять "да" либо "нет".. плюс "+" либо минус "-"..

По результатам, чего больше, чего меньше, подведу итог, и приму решение, выкладывать новый материал..

Спасибо..

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

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

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

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

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

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

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

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