Техническое письмо

Техническое письмо - это когда мы объясняем сложную штуку (кнопки, код, болты, законы) так, чтобы другой человек понял её с первого раза и не накосячил.

Документация

Документация — это совокупность документов, созданных для описания, объяснения, сопровождения или управления продуктом, системой, процессом или проектом.

Виды документации

В мире существует очень, ОЧЕНЬ много видов документов. Вы даже себе не представляете, насколько.

Технический писатель

Технический писатель - специалист, занимающийся написанием технической документации.

Качество документации

Хорошая документация — это та, которую не нужно объяснять устно. Если команда постоянно уточняет — А в документе это имеется в виду так-то? — значит, документация недостаточно ясна.

Архитектура документации — это целенаправленное проектирование структуры, содержания, форматов, потоков и взаимосвязей всех документов, сопровождающих продукт или систему на всех этапах её жизненного.

Экосистема технического письма

Markdown Extra — используется в некоторых генераторах (например, в MkDocs) для расширенных возможностей.

Word и Excel в проектной документации

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

Стилевые паттерны технической документации

Стилевой паттерн - это готовый шаблон того, как писать и оформлять код или текст.

Техническое задание по ГОСТ

Техническое задание (ТЗ) — это документ, в котором заказчик и исполнитель договорились о правилах игры до того, как кто-то начал что-то делать.

Спецификация по ГОСТ

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

ПМИ по ГОСТ

ПМИ - это документ, в котором написано, как будут проверять, работает ли программа так, как надо.

ПЗ по ГОСТ

Если используется open-source компонент, указывайте название, версию, лицензию и источник.

Руководство системного программиста по ГОСТ

Руководство системного программиста — это инструкция для того, кто ставит и настраивает программу на сервере.

Руководство программиста по ГОСТ

Рекомендация — оформлять в виде таблиц. Ошибка — смешивать требования к системе и требования к разработке.

Руководство оператора по ГОСТ

Руководство оператора - это документ о том, как выполнять конкретные операции — пошагово, с картинками интерфейса.

Руководство по техническому обслуживанию по ГОСТ

Основано на ГОСТ 19.508-79.

Руководство пользователя по ГОСТ

Основано на ГОСТ Р 59795 – 2021. Руководство пользователя о том, как выполнить сценарии, нужные пользователю: зарегистрироваться, заказать товар, посмотреть баланс, выгрузить отчёт.

Руководство администратора по ГОСТ

Не указывайте любой современный браузер. Указывайте конкретные версии и режимы, например Chrome >=115.

Навигатор по нормативной документации

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

Документирование API с использованием Swagger/OpenAPI

API — прикладные программные интерфейсы — служат основным каналом взаимодействия между компонентами систем, между внутренними сервисами и внешними клиентами, между разработчиками и пользователями.