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

Как подход Docs-as-a-code применили в создании документации для TestY TMS

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

Для ведения документации выбрали подход Docs-as-a-code. Документация хранится вместе с кодом приложения. Для написания и сборки использовали более-менее классическое сочетание: rST-формат в связке со Sphinx. 

Инженеры уверены, что такой вариант предоставляет большую гибкость, чем стандартный MD. К тому же,  rST в связке со Sphinx — стандарт документации для open source-проектов.

Разработчики поддерживают документацию в актуальном состоянии, поэтому рассчитывают, что в дальнейшем любое изменение текущей функциональности, как и разработка новой, будет сопровождаться обновлением документации. Это будет одним из Definition of Done для реализации фич.

Помимо документации в релизе 2.1 появилась темная тема и другие обновления интерфейса. Читайте о них в статье →

Pull/Merge Request для согласования требований и документации

Аналитики и технические писатели, признайтесь: сколько раз вы теряли время, сравнивая версии документов в MS Word? Компьютер тормозит, красные и синие правки сливаются в кашу, а поиск согласования в бесконечной переписке или Confluence превращается в квест.

Есть решение — берем механизм Pull/Merge Request и применяем его к текстам! Что получаем:

• Все правки в одном месте. Редактируйте несколько документов сразу и смотрите изменения в едином окне. Забудьте про переключение между файлами и версиями!

• Подробная подсветка. Все правки видны построчно или в удобном визуальном редакторе — сразу ясно, что добавили, убрали или исправили.

• Простое согласование. Назначайте проверяющих и получайте их апрувы прямо в интерфейсе. Никаких "ок" в письмах или мессенджерах!

• Полная история. Все комментарии, согласования и версии сохраняются. В любой момент можно вернуться и проверить, кто, что и когда утвердил.

• Экономия времени. Gramax объединяет редактирование, ревью и согласование в одном месте — больше не нужно жонглировать Word, Confluence и почтой.

И все это в Gramax! Как всегда: бесплатно и с открытым исходным кодом.
Все как в коде, только проще.

💥 Майская версия Gramax 💥

Что нового мы добавили в open source-платформу для управления технической документацией Gramax.

• ИИ-поиск для портала документации. Раньше поиск по документации был ограничен точным совпадением слов, теперь можно подключить ИИ-поиск от любого провайдера (например, OpenAI, Anthropic и др.) и искать по смыслу. Даже при неточном запросе пользователь получит релевантные результаты. Поддерживается как облачное подключение, так и запуск собственного сервера — для тех, кому важна приватность.

• ИИ для создания и редактирования текста. В пространстве редактора можно также подключить ИИ. Он позволит написать текст с нуля: например, если не удается придумать структуру статьи. А также отформатировать существующий текст. В случаях, если его нужно сократить, сделать более формальным или структурированным.

• Шаблоны. Добавили возможность создавать шаблоны со свойствами и использовать их в статьях. 

• Заметки. Теперь можно прямо в каталоге сохранять идеи и предложения для изменения документации. Заметки сохраняются в репозитории, но не отображаются на портале для чтения. 

• Расширенный редактор сниппетов. Теперь сниппеты можно оформлять как и обычную статью без ограничений. 

• Выбор формата для исходных файлов. Добавили 2 дополнительных формата хранения статей — XML и GitHub Flavored Markdown. Изменить формат можно в настройках каталога.

• Вход для внешних пользователей в Gramax Enterprise Server. Добавили возможность настроить вход на портал для чтения по почте: таким читателям не нужно иметь учетную запись в SSO. Достаточно указать свою почту при входе и ввести одноразовый код.

О других изменениях читайте в статье — https://gram.ax/resources/docs/whats-new

PlantUML | Шаблон для описания таблиц БД

Делюсь с Вами разработанным мною шаблоном, для описания таблицы БД в PlantUML, c элементами автоматизации, описание которых указанно в комментариях.

Всем привет!
Делюсь с Вами разработанным мною шаблоном, для описания таблицы БД в PlantUML, c элементами автоматизации, описание которых указанно в комментариях.

Протестировать можете тут, а сам код шаблона указан ниже:

 ' Шаблон описания таблицы БД (в PlantUML)
@startuml

skinparam {
' Параметры для управления нижним колонтитулом
    FooterFontColor #blue
    FooterFontSize 12
' Параметры для управления легендой
    LegendBackgroundColor #lightblue
    LegendBorderThickness 0
}

' Переменные для ускорения описания таблицы
' - PRIMARY KEY можно указывать как: "$PK"
    !$PK="  <size:11><#DarkKhaki:key:></size> (PK)  "
' - FOREIGN KEY можно указывать как: "$FK"
    !$FK="  <size:11><#DeepPink:key:></size> (FK)  "
' - NOT NULL (N-N) можно указывать как: "$NN"
    !$NN="  <#LightGreen> **N-N**  "
' - NULL можно указывать как: "$N"
    !$N = "  <#LightCoral> **NULL**  "


' Переменные для ускорения добавления информации о таблице
' - Наименование таблицы БД (латинское)  
    !$table_name="Наимнование_таблицы_БД"
' - Краткое описание таблицы (на русском) 
    !$description="Краткое описание таблицы (на русском)"
' - Ссылка на описание таблицы (на русском)
    !$doc_url="Ссылка"

' Контакты, отображаемые в нижнем колонтитуле
    !$autor ="Зимин Антон"
    !$email ="antzim_in@ya.ru"
    !$telegram="antzim_in"

' Заголовок документа, формируется автоматически из заполненных выше параметров (при необходимости можно удалить)
    title $table_name | $description

' Легенда (может быть заполнена любыми необходимыми данными)
' - "right" говорит о том, что легенда будет расположена справа 
legend right
**Легенда:**
| Версия документа: | 1.0.0 |
end legend



' Описание таблицы
' - заголовок таблицы, с кликабельной ссылкой (если выгружать в SVG) формируется автоматически
class "[[$doc_url $table_name]] ($description)" as $table_name << (T,#FF5722) >>{

|=   PK,FK  |=   Поле   |=   Тип   |=   Обязательность   |=   Значение\n по умолчанию   |=   Описание   |
| $PK | id | serial | $NN | | Идентификатор записи в таблице |
| $FK | subscriber_id | integer | $NN | | Идентификатор записи в таблице subscriber |
|     | electronic_address | varchar(255) | $N | | Электронный адрес \n клиента |
|     | created_at | timestampz | $NN | now() | Дата и время создания записи в БД |
|     | updated_at | timestampz | $NN | now() | Дата и время обновления записи в БД |
}

' Нижний колонтитул (формируется автоматически из введенных параметров)
footer © $autor | tg: [[https://t.me/$telegram @$telegram]] | email: $email
@enduml

Буду рад Вашим комментариям, отзывам, а если еще и поднимите карму то буду крайне благодарен.

Всем спасибо.
----

Пообщаться со мной можно в telegram: @antzim_in
P.S. Также, если Вам интересно, я веду telegram канал @sa_chulan и буду очень рад Вашей подписке.

Тестирование документации: залог успешной разработки

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

Почему важно проверять документацию заранее?

Представьте, что вы собираетесь строить дом. У вас есть план, но если он неполный или в нём ошибки, вместо уютного дома может получиться что-то с одной стеной или без крыши. В программировании примерно так же: если требования, то есть документация, составлены плохо, программа может не работать или работать неправильно.

Проверка требований до начала разработки помогает находить проблемы раньше, чем они превратятся в баги. Чем раньше найдёшь ошибку, тем меньше потом придётся исправлять. Это называется "Shift-Left Testing", что по сути означает — тестировать раньше, чтобы потом не было больно.

Вот какие проблемы можно найти на этом этапе:

• Противоречия в требованиях: например, в одном месте написано "сохранить данные", а в другом — "удалить данные". Так какой из них правильный?

• Неоднозначные формулировки: когда написано так, что можно понять по-разному, и каждый разработчик это понимает по-своему.

• Отсутствие важных условий: что-то важное просто забыли описать, и программа не знает, что с этим делать.

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

Как можно тестировать требования?

Есть несколько способов проверить, что в документации нет ошибок:

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

• Чтение и обсуждение: собираемся, читаем вместе, обсуждаем и находим проблемы.

• Моделирование: создаём простые схемы, чтобы понять, как всё должно работать.

• Анализ текста с помощью ИИ: современные программы могут сами искать ошибки в тексте требований.

Что будет дальше?

Ниже можете видеть видео, где видно, как наш инструмент TestWriter проводит проверку документации с помощью ИИ. Это пока что прототип, но уже видно, как много ошибок можно найти ещё до начала разработки.

Полезные материалы по теме:

• Тестирование требований — Teamlead Roadmap: Простое объяснение, зачем проверять требования перед началом разработки.

• Критерии качества требований с примерами — Habr: Примеры, как сделать документацию понятной и понятной для всех.

• Тестовая документация: что учитывать при постановке эффективного процесса тестирования — Habr: Как правильно описывать требования, чтобы не возникало путаницы.

• Роль формализации требований в тестировании программного обеспечения — КиберЛенинка: Почему важно прописывать требования максимально чётко.

• Тестирование требований — Особенности — Quality Lab: Как работают с требованиями на практике и какие ошибки бывают.

P.S.: а вот ссылка на мой блог в Telegram: https://t.me/it_vadimqa

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

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

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

# Статус

Черновик\Утверждено\Заменено на 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, журналы изменений, архитектурные документы и комментарии к коду оба эти проекта объясняют свой дизайн таким образом, чтобы даже новичок может понять в кодовой базе, где что находится, как что-то делается и почему это делается именно так. Он порекомендовал разработчик, желающим лучше документировать свой код и архитектуру программного обеспечения, брать для примера эти проекты.

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

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

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

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

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

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