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

ОБЯЗАТЕЛЬНОДЛЯ НОВИЧКОВ

Руководителю Аналитику Техническому писателю

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

Давайте с ключевого. Технический писатель - это роль. Её может исполнять кто угодно - аналитик, разработчик, инженер, юрист, методист, художник. Суть именно в искусстве превратить хаос в инструкцию.

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

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

Целевая аудитория может быть разная:

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

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

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

Аналитик нарисует слишком сложную схему, где стрелки идут крест-накрест, а программисты по итогу сделают не то. Тут конечно, косяк аналитика, но без этого никак.

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

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

Пример - руководства по ГОСТ. Они формальные, делаются по стандартному шаблону, но в реальных условиях абсолютно нечитабельны и неприменимы! Поэтому существуют альтернативные варианты, типа баз знаний или инструкций.

Техническое письмо нужно, чтобы готовить все эти документы, экономя время и нервы, отвечая на вопросы "что делать?", "в каком порядке?" и "что будет, если сделать не так?".

Понятие и цели технического письма

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

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

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

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

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

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

Ясность позволяет подавать информацию доступно, без излишней сложности и двусмысленности.

Структурированность - логичная организация текста (заголовки, списки, иерархия), что позволяет читателю быстро находить нужное.

Целевая направленность текста учитывает аудиторию - её уровень знаний, задач и контекст использования.

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

Истоки

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

Одним из первых известных образцов считается трактат Витрувия «Об архитектуре» (I век до н.э.) — десять книг, в которых римский инженер не только описал принципы строительства, но и ввёл систему терминологии, чертежей и инструкций.

В Средние века арабские учёные, такие как Аль-Джахиз и Аль-Джазари, писали подробные технические манускрипты с описанием механизмов, автоматов и военных машин — схемы, пошаговые инструкции, даже «юнит-тесты» в виде описаний работоспособности. Это была уже полноценная документация.

Системность

С приходом промышленной революции XIX века техническое письмо стало системным. Чертежи, спецификации, операционные инструкции, патентные описания — всё это требовало стандартизации. Заводы не могли работать без чётких регламентов. Военные проекты — без точных описаний систем. А когда в середине XX века человечество запустило первые компьютеры, стало ясно: без документирования знаний масштабные проекты просто невозможны.

Чертёж — это графический документ, выполненный в соответствии с установленными правилами проектирования и стандартизации (например, ГОСТ, ISO, ANSI), который в масштабе и с точными размерами изображает форму, конструкцию и параметры изделия, детали, здания или системы.

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

Спецификация — это структурированный документ, в котором перечислены и описаны компоненты, параметры, требования и характеристики изделия, системы или проекта. Она отвечает на вопрос: «Из чего это состоит и какие у этого требования?»

Цель спецификации — обеспечить точное понимание состава и требований к продукту для разработчиков, инженеров, закупщиков и контролеров.

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

Цель операционной инструкции — минимизировать ошибки, обеспечить стандартизацию процессов и защитить пользователя и оборудование.

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

Цель патентного описания — обосновать новизну и изобретательский уровень решения, чтобы получить правовую защиту.

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

Строгость и многоуровневость

Космическая гонка и программы NASA стали поворотным моментом. Там, где ошибка в инструкции могла стоить жизни, документация превратилась в строгий, верифицируемый, многоуровневый процесс. Каждое решение, каждый компонент, каждый тест — фиксировались. Появились стандарты: MIL-STD, IEEE, ISO. Документация стала обязательной частью инженерной дисциплины.

MIL-STD (United States Military Standard), это военный стандарт США, система стандартов, разработанных Министерством обороны США для унификации проектирования, производства, испытаний и документирования военной техники, оборудования и программного обеспечения. К примеру, MIL-STD-461 — требования к электромагнитной совместимости, MIL-STD-810 — методы испытаний на устойчивость к внешним воздействиям (температура, вибрация, влажность), MIL-STD-40051 — стандарт оформления технической документации для военных систем.

Разработан MIL-STD в середине XX века, в период Второй мировой войны и Холодной войны, когда США столкнулись с проблемой несовместимости оборудования от разных поставщиков. Единые стандарты позволили упростить логистику, ремонт и взаимозаменяемость деталей.

IEEE (Institute of Electrical and Electronics Engineers, Институт инженеров по электротехнике и электронике) - это международная профессиональная организация, разрабатывающая технические стандарты в области электротехники, электроники, информационных технологий и телекоммуникаций.

IEEE 802 — стандарты локальных сетей (например, IEEE 802.11 — Wi-Fi).
IEEE 754 — стандарт представления чисел с плавающей запятой.
IEEE 12207 — стандарт процессов жизненного цикла программного обеспечения.
IEEE образован в 1963 году путём слияния двух организаций: American Institute of Electrical Engineers (AIEE) и Institute of Radio Engineers (IRE). Стандартизация стала одной из ключевых миссий — особенно с ростом цифровых технологий. Многие IT-документы (особенно по сетям, API, протоколам) ссылаются на IEEE.

ISO (International Organization for Standardization, Международная организация по стандартизации) - это глобальная сеть национальных стандартов, разрабатывающая международные стандарты по самым разным сферам — от качества и безопасности до информационных технологий и экологии.

ISO 9001 — система менеджмента качества.
ISO/IEC 27001 — безопасность информации.
ISO/IEC 2382 — словарь терминов в области информационных технологий.
ISO 20607 — стандарт по технической документации для безопасного использования машин.

Организация создана в 1947 году в Лондоне представителями 25 стран. Цель — устранить барьеры в международной торговле и техническом сотрудничестве за счёт единых правил. ISO устанавливает международные нормы для структуры, содержания и терминологии технической документации. Например, стандарт ISO 20607 напрямую регулирует, как оформлять руководства по эксплуатации, чтобы они были понятны в любой стране.

ANSI (American National Standards Institute, Американский национальный институт стандартов) - это некоммерческая организация, координирующая разработку и внедрение добровольных стандартов в США. ANSI не создаёт стандарты сам, но утверждает и аккредитует стандарты, разработанные другими организациями (включая IEEE, ASME, NIST).

ANSI Z535 — стандарты предупреждающих знаков и маркировки.
ANSI/INCITS — стандарты в области информационных технологий.
ANSI C (теперь ISO/IEC 9899) — стандарт языка C.

Основан в 1918 году как American Engineering Standards Committee (AESC). Создан по инициативе пяти инженерных ассоциаций и правительственных ведомств для устранения дублирования и несогласованности в промышленных стандартах. ANSI определяет форматы, символы, цвета и терминологию, используемые в технической документации в США. Особенно важен при создании инструкций по безопасности, маркировке оборудования и документации для рынка США.

ГОСТ (Государственный стандарт) это система стандартов, действующих на территории бывшего СССР и в настоящее время — в России и других странах СНГ. Охватывает технику, производство, строительство, IT, документооборот и многое другое.

ГОСТ 2.105–2019 — общие требования к текстовым конструкторским документам.
ГОСТ Р 21.1101–2020 — систему проектной документации для строительства.
ГОСТ 7.0.12–2011 — требования к оформлению научных и технических документов.
ГОСТ 34 — стандарты в области автоматизации и программирования (например, ГОСТ 34.13-2015 — шифрование).

Первые ГОСТы были введены в 1925 году в СССР. В 1968 году началась масштабная унификация под названием ЕСКД (Единая система конструкторской документации) и ЕСПД (Единая система программной документации) — они стали основой для оформления чертежей и IT-документации в СССР.

В России и странах СНГ ГОСТы — обязательный ориентир при создании технической документации. Особенно строго соблюдаются в государственных, оборонных и промышленных проектах.

Стандартизация позволила сделать мир документации более организованным и единообразным, и фактически «подмяла» под себя техническое письмо.

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

Комментарии в коде

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

// Вычисление факториала с помощью рекурсии
int factorial(int n) {
    if (n <= 1) return 1;
    return n * factorial(n - 1);
}

Ещё в 1950-х годах, с появлением первых языков высокого уровня (например, FORTRAN, COBOL, ALGOL), стало очевидно, что код нужно сопровождать пояснениями. Ранние программисты (часто математики и инженеры) писали заметки прямо в листингах — сначала на полях, потом в теле программы.

В FORTRAN (1957) комментарии обозначались символом C в первой колонке. К 1970-м годам комментарии стали стандартной практикой, особенно в языках вроде C, где сложность кода требовала пояснений.

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

В 1970-х появились уже первые руководства, технические описания и справочники, создаваемые разработчиками для других разработчиков или пользователей. Это могли быть PDF, текстовые файлы (.txt), бумажные мануалы. К примеру, руководства по языку C (Керниган и Ритчи, 1978), справочники по операционным системам (UNIX, VMS), описания библиотек и утилит.

С ростом сложности программного обеспечения (особенно в академических и военных проектах) стало невозможно полагаться только на код. Нужны были внешние документы, объясняющие архитектуру системы, интерфейсы и принципы использования. Соответственно, в 1970-x Bell Labs (там, где создавали UNIX и C), активно писали документацию и появились man-страницы в UNIX - первые электронные справочники. Компании вроде IBM и DEC выпускали толстые тома с описанием своих систем. Разработчики впервые стали техническими писателями по умолчанию.

API

В 1980-х, для стандартизации взаимодействия между системами, с развитием операционных систем, графических интерфейсов и сетевых протоколов (TCP/IP, HTTP), разработали первые API.

API (Application Programming Interface) — набор правил, по которым программы обмениваются данными. Спецификация API описывает - какие методы доступны, какие параметры принимают, какие ответы возвращают, как авторизоваться и обрабатывать ошибки.

Первыми были Microsoft и Apple, которые публиковали API для разработки под Windows и Mac OS. А с развитием веб-инфраструктуры, HTTP, HTML, CGI появились и прочие документы.

В 1998 году Sun Microsystems опубликовали Javadoc и спецификации для Java API. В 2000-х уже появились SOAP, WSDL, что повлекло за собой XML-описания веб-сервисов.

А в 2010-х, с развитием REST и стандартов вроде OpenAPI (ранее Swagger), спецификации и вовсе стали машиночитаемыми.

Машиночитаемость

Говоря об XML, следует упомянуть об XML-документации и аннотациях. В 1990-х, появились способы встраивать документацию прямо в код, чтобы она могла автоматически извлекаться и превращаться в HTML, PDF и другие форматы.

К примеру, C# и .NET в 2000-х, подготовили специальные комментарии, которые парсятся утилитой Sandcastle и превращаются в официальную документацию:

/// <summary>
/// Вычисляет сумму двух чисел.
/// </summary>
/// <param name="a">Первое число</param>
/// <param name="b">Второе число</param>
public int Add(int a, int b) { ... }

JavaDoc же использует специальные комментарии /** ... */ с тегами @param, @return, @throws. А для генерации используется одноимённая утилита, которая генерирует HTML-сайт с документацией.

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

@Deprecated
public void oldMethod() { ... }

Такие аннотации помогают документировать поведение, безопасность, маршруты (в Spring: @GetMapping) — и автоматически отражаются в документации.

Соответственно, в Python появился Sphinx + docstrings, а в JavaScript - JSDoc.

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

В тот же период развивался и еще один аспект, касающийся документации - SDK (Software Разработка Kit), набор инструментов, позволяющий разработчикам создавать приложения для определённой платформы. Он включает библиотеки, API, примеры кода, документацию, отладчики. эмуляторы, словом, всё что нужно для старта. К примеру - Android SDK, AWS SDK, Facebook SDK. Они появились, потому что компании заинтересовались привлечением сторонних разработчиков. SDK стали маркетинговым инструментом — чем лучше SDK, тем больше разработчиков присоединяется.

Базы знаний, вики и внутренние порталы появились в 1990-х. Собственно, Wiki как Confluence, Notion, MediaWiki, базы знаний как Zendesk, ServiceNow и корпоративные сайты с документацией, процессами, FAQ.

В 1995 году появился WikiWikiWeb, первая вики. В 2000-х компании начали использовать MediaWiki для внутренних целей, пока в 2004 Atlassian не запустила самый масштабный проект для бизнеса - Confluence. Это первая коммерческая вики, которая позволила очень классно организовать работу в компании.

А уже в 2010-х появились Slack, Notion, Google Workspace, Яндекс и прочие сервисы с интеграцией чатов, документов, баз знаний. Сейчас вики практически самый важный инструмент любой команды, охватывающий все аспекты - от онбординга и организационных моментов до работы DevOps.

Чем вики фундаментально отличается от документации другого вида? Своей актуализируемостью и живостью. Представьте - документацию надо править, согласовывать и утверждать. А вики можно просто за пару секунд поправить и всё.

В настоящее время появилась философия Docs-as-Code, примерно с 2010-х. Она подразумевает, что документация пишется, хранится и развивается так же, как и код - в системах контроля версий (Git), с помощью Markdown, через CI/CD пайплайны, с pull request’ами и ревью. То есть, под влиянием технологий DevOps и Agile-методологий, и конечно open-source проектов вроде Linux, Kubernetes, React, документация стала ещё живее.

Потому что открытые проекты хранят свою документацию на GitHub в README.md, docs/, а инструменты вроде Jekyll, Hugo, Docusaurus, MkDocs генерируют аж целые сайты из Markdown! Со временем даже крупные компании (Google, Microsoft, Netflix) перешли на docs-in-repo, когда документация располагается в репозитории, живя рядом с кодом.

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

См. также

Другие статьи этого же раздела в боковом меню (как на странице «О разделе»).

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