Microsoft, Google, IBM и Apple пришли к четырём разным моделям технической документации. Microsoft построила наиболее цельную инфраструктуру вокруг документации и обучения, Google — самый сильный открытый редакционный ориентир для ежедневной работы, IBM — формальную систему качества и типов контента, Apple — документацию, которая живёт рядом с исходным кодом и собирается тем же инструментарием, что и продукт.
Мы сравнили официальные порталы, style guides, contributor guides, архивы, authoring toolchain, поиск, версии, accessibility, localization и машинный доступ к документации. Цель — не выбрать самый красивый портал, а понять, какая модель сильнее как рабочая система и какие решения стоит перенести в собственную документационную практику.
Методика исследования
Исследование основано на открытых первичных источниках и публичной документации Google, Microsoft, IBM и Apple. Для каждой компании проверены основной портал, style guide, contributor guidance, архив, authoring toolchain, версии, механизмы обратной связи, accessibility/localization и доступ документации для машинного поиска. Все четыре системы оценены по одному набору из девяти критериев по шкале 0–2. Дата среза — 14 августа 2026 года.
Кто сильнее по совокупности возможностей
Microsoft занимает первое место с 17 баллами из 18. IBM набирает 15, Google — 14, Apple — 13. Наибольший отрыв Microsoft получает за сочетание единого портала, версий, learning-контента, authoring-процесса и официального доступа к базе знаний из AI-инструментов. Девять критериев оцениваются по шкале 0–2; максимум — 18 баллов.
Что именно оценивалось
0 — отсутствует · 1 — реализовано частично или только в части продуктов · 2 — полноценная системная возможность
| Критерий | Microsoft | IBM | Apple | |
|---|---|---|---|---|
| Единый портал и навигация | 2 | 1 | 2 | 2 |
| Публичный style guide | 2 | 2 | 2 | 1 |
| Видимая актуализация правил | 2 | 2 | 1 | 1 |
| Tutorial / how-to / reference | 2 | 2 | 2 | 2 |
| Версии и архив | 2 | 1 | 2 | 2 |
| Обратная связь и участие | 1 | 1 | 1 | 1 |
| Интеграция с authoring toolchain | 2 | 1 | 2 | 2 |
| Accessibility, inclusivity, localization | 2 | 2 | 2 | 2 |
| Доступ документации для ИИ/агентов | 2 | 2 | 1 | 0 |
Масштаб документационных систем
Масштаб у четырёх компаний проявляется по-разному. Microsoft исторически публиковала сотни тысяч страниц, Google открыла машинный поиск сразу по множеству developer-доменов, IBM строит портал вокруг поиска, а Apple сохранила крупный архив прежних поколений документации. Ниже — четыре проверяемых числовых маркера из официальных источников.
| Компания | Проверяемый маркер масштаба | Источник |
|---|---|---|
| Microsoft | MSDN Online уже в 1998 году содержал более 250 000 страниц. | [M5] |
| Developer Knowledge MCP в 2026 году перечисляет 18 групп/доменов документации, включая Android, Chrome, Firebase, Google Cloud, Flutter, TensorFlow и другие. | [G5] | |
| IBM | IBM сообщает, что 80% трафика IBM Documentation приходит через поиск; поиск объединяет product docs с другими техническими материалами IBM. | [I8] |
| Apple | Официальный Documentation Archive содержит 5 219 архивных документов. | [A2] |
Как документация превратилась в инфраструктуру
За 1990–2026 годы техническая документация прошла путь от больших библиотек руководств к платформам, связанным с Git, IDE, поиском, обучением и AI-инструментами. Самое заметное изменение произошло не во внешнем виде страниц, а в том, где живёт документация, как она обновляется и кто может её потреблять.
Запускается Microsoft Developer Network: техническая информация становится отдельной профессиональной службой для разработчиков. [M5]
MSDN Online превышает 250 000 страниц. Публикация документации превращается в отдельную инфраструктурную задачу. [M5]
docs.microsoft.com запускается после исследований с сотнями разработчиков и ИТ-специалистов. В новую модель входят Markdown, GitHub-вклад, навигация по намерению пользователя и более короткие статьи. [M6]
1 апреля IBM Knowledge Center заменён IBM Documentation: меняются название, адрес и пользовательский интерфейс основного портала продуктовой документации. [I5]
DocC появляется в Xcode 13 и затем становится open source. Source comments, Markdown-статьи, tutorials и сборка документации сходятся в одном toolchain. [A4]
Google Style Guide усиливает правила accessibility, semantic tables, global audience, структуры абзаца, ARIA и task-oriented подачи. [G2]
The Swift Programming Language переезжает на DocC; при переносе принимаются более 50 pull requests, а переводы получают тот же publishing pipeline. [A5]
Generative AI, prompts, accessibility, inclusive language, code formatting и UI wording становятся обычными темами редакционных руководств. [G2]
Microsoft Learn публикует MCP-сервер для поиска и получения официальной документации из AI-инструментов и агентов. [M4]
Google Developer Knowledge MCP открывает машинный поиск по официальной документации разработчика и перечисляет 18 групп покрываемых продуктов и доменов. [G5]
В официальной документации CICS появляются AI-generated search results для поисковых запросов от трёх слов. [I7]
Как менялись сами style guides
История обновлений Google и Microsoft показывает, как в повседневную работу автора вошли task design, accessibility, global writing, разметка кода и правила работы с AI.
| Год | Компания | Что менялось для автора | Источник |
|---|---|---|---|
| 2021 | Контекст задачи, imperative в процедурах, отказ от пустого «run the following command», global audience и timeless documentation. | [G2] | |
| 2021 | Microsoft | Inclusive language становится отдельной частью guide; терминология сильнее учитывает bias-free communication. | [M1] |
| 2022 | Accessibility входит в правила таблиц, UI, пунктуации и когнитивной нагрузки. Guide учитывает Markdown и authoring experience. | [G2] | |
| 2022 | Microsoft | Расширяются правила UI-текста и местоимений, включая pronouns в AI-generated content. | [M1] |
| 2023 | Усиливаются paragraph structure, ARIA, global language и требование сохранять смысл без изображений и анимации. | [G2] | |
| 2023 | Microsoft | Accessibility language включает people-first и identity-first wording и screen-reader-friendly tables. | [M1] |
| 2024 | В word list входит generative AI; одновременно усиливаются timeless docs, alt text, captions и точность терминологии. | [G2] | |
| 2024 | Microsoft | Появляются отдельные правила для prompt/prompting и написания AI prompts. | [M1] |
| 2025 | Добавляется prescriptive documentation; task design, links, code и accessibility всё теснее рассматриваются вместе. | [G2] | |
| 2025 | Microsoft | Обновляются code formatting, доступные minus signs, identity language и разговорный тон. | [M1] |
| 2026 | Перестраивается global-audience guidance, уточняются UI context, code formatting и AI terminology. | [G2] | |
| 2026 | Microsoft | Screen reader, alt text, AI prompts, emoji accessibility, tooltips и UI wording входят в регулярное обновление guide. | [M1] |
Как менялась работа технического писателя
Техпис постепенно перестал быть только автором страницы или руководства. Современная роль включает информационную архитектуру, типизацию контента, работу рядом с кодом, контроль актуальности, accessibility, localization, метаданные и подготовку знаний так, чтобы ими одинаково уверенно пользовались человек, поиск, IDE и AI-агент.
| Период | Основной объект | Типичные инструменты | Редакционный фокус | Доставка | Роль техписа |
|---|---|---|---|---|---|
| 1990–2015 | Руководство / HTML-страница | Word, CMS, XML, специализированная публикация | Полнота, единообразие, reference | Web + PDF | Автор-специалист |
| 2016–2020 | Task-oriented портал | CMS + Git/Markdown | Поиск, task success, короткий web-текст, IA | Центральный портал | Владелец контента внутри product workflow |
| 2021–2024 | Структурированная база знаний рядом с кодом | Git, Markdown, DITA, DocC, CI | Семантика, reuse, accessibility, localization | Портал + IDE + generated reference | Information architect + партнёр по автоматизации |
| 2025–2026 | Источник знаний для человека и ИИ | Source + metadata + schemas + retrieval interfaces | Grounding, retrievability, factual quality, machine consumption | Портал + IDE + search + MCP/AI | Редактор, системный дизайнер, verifier |
Главное изменение профессии — ответственность за систему знаний. Написать страницу по-прежнему важно, но ценность техписа всё чаще определяется тем, насколько хорошо документация устроена, проверяется, обновляется, находится и подключается к разработке.
Какие практики стоит забрать у Microsoft, Google, IBM и Apple
Четыре компании полезны по разным причинам. Копировать их порталы целиком бессмысленно; гораздо интереснее разобрать конкретные решения, которые можно перенести в документационный процесс небольшой или средней команды.
| Сначала задача, потом действие | Условие и контекст ставятся перед шагом. Читатель сначала понимает, относится ли инструкция к его сценарию, и только затем выполняет команду. |
|---|---|
| Писать prescriptive documentation | Когда есть рекомендуемый путь, Google советует не маскировать решение списком равноправных вариантов. Для пользователя полезнее ясная рекомендация с точными условиями применения. |
| Встроить accessibility в редактуру | Таблицы, ссылки, изображения, UI-элементы и даже пунктуация рассматриваются как часть доступности. Проверка идёт во время написания, а не после публикации. |
| Писать для глобальной аудитории | Локальные идиомы, двусмысленные обороты и культурные отсылки убираются ещё в исходном тексте. Такой материал легче переводить и проще понимать международной аудитории. |
| Поддерживать style guide как живой инструмент | Changelog обновляется постоянно: AI terminology, UI wording, code formatting, lists, accessibility. Правило можно открыть в момент реальной редакторской задачи и получить актуальный ответ. |
Microsoft
[M2]| Строить документацию как платформу | Learn объединяет документацию, обучение, версии, навигацию и механизмы обратной связи. Для большой продуктовой линейки это сильнее набора отдельных сайтов и PDF. |
|---|---|
| Организовывать контент вокруг намерения пользователя | Ещё при запуске docs.microsoft.com Microsoft перестраивала материалы вокруг задач: начать работу, спланировать, развернуть, управлять, устранить проблему. Структура портала следует работе пользователя, а не оргструктуре компании. |
| Показывать свежесть и версию | Дата обновления и версия продукта становятся частью доверия к странице. Пользователь быстрее понимает, относится ли материал к его среде. |
| Поддерживать style guide как живой продукт | Changelog регулярно обновляется по AI prompts, accessibility, terminology, UI wording и developer text. Редакционный стандарт развивается вместе с продуктом. |
| Готовить документацию для машинного доступа | Learn MCP позволяет агентам искать официальные статьи, получать полный текст и code samples. Документация становится не только web-страницей, но и доверенной knowledge base для инструментов разработчика. |
IBM
[I2]| Проверять качество по отдельным признакам | Вместо общего «текст хороший» IBM раскладывает качество на task orientation, accuracy, completeness, clarity, style, organization и retrievability. Ревью превращается из вкусового спора в проверку конкретных свойств материала. |
|---|---|
| Использовать формальный content model | IBM связывает content type, subject, item и attributes. How-to, troubleshooting, release notes, API reference и UI content получают понятное место и назначение. |
| Определять качество до публикации | В content strategy отдельно задаются стандарты качества, метрики успеха, feedback loops и обслуживание уже выпущенных материалов. Документация получает собственное определение done. |
| Приоритизировать контент по пользовательским исследованиям | IBM публикует результаты исследования 1400+ пользователей и выделяет наиболее ценные типы контента. Приоритет определяется не привычкой команды, а тем, что помогает пользователю решить задачу. |
| Проектировать поиск как часть документации | 80% трафика IBM Documentation приходит через поиск. Retrievability поэтому становится полноценным свойством качества, а не задачей отдельной поисковой команды. |
Apple
[A3]| Держать документацию рядом с кодом | DocC собирает source comments, Markdown articles, assets и API reference в одной системе. Документация меняется в том же version-control процессе, что и код. |
|---|---|
| Собирать документацию как код | Build Documentation в Xcode делает документацию проверяемым build artifact. Ошибки ссылок и структуры можно ловить до публикации, а не после релиза. |
| Не разделять reference и обучение | API reference, conceptual articles и пошаговые tutorials проходят через один toolchain и могут ссылаться друг на друга. Пользователь получает не отдельные острова контента, а связанную систему. |
| Доставлять знания туда, где работает разработчик | DocC-документация может открываться в Xcode или публиковаться на web. Хорошая developer documentation не заставляет постоянно уходить из рабочего контекста. |
| Считать документацию частью developer experience | Apple проектирует не только текст, но и навигацию между symbols, articles и tutorials. Для API-команд это важный сдвиг: документация становится частью интерфейса платформы. |
Официальные источники
Основа исследования — первичные официальные источники Google, Microsoft, IBM и Apple. Ссылки ведут на документы, по которым проверялись факты, правила и числовые показатели.
Итог: одной идеальной школы нет, но победители по задачам очевидны
| Компания | Где компания сильнее | Что это даёт техническому писателю |
|---|---|---|
| Microsoft | Документационная платформа | Если выбирать одну систему целиком, Microsoft сегодня выглядит сильнее остальных. Learn связывает документацию, обучение, версии, feedback и машинный доступ; портал проектируется как продуктовая инфраструктура, а не как склад статей. Главный урок — документации нужен собственный platform thinking. |
| Редакционная работа | Google даёт лучший открытый рабочий справочник именно для техписа: task-first подача, prescriptive documentation, global audience, accessibility, терминология и живой changelog. Его сильная сторона — правила, которые можно открыть утром и сразу применить к конкретному абзацу, процедуре или UI-тексту. | |
| IBM | Качество и content model | IBM превращает субъективное «хорошо написано» в проверяемую систему. Семь характеристик качества, формальный content model, пользовательские исследования, feedback loops и отдельная работа с retrievability дают зрелой команде основу для ревью, метрик и архитектуры контента. |
| Apple | Документация рядом с кодом | Apple показывает наиболее убедительную модель для API и developer documentation: source comments, Markdown-статьи, tutorials, cross-symbol links и API reference проходят через DocC и developer toolchain. Документация становится частью сборки продукта, а не отдельной публикацией после разработки. |
Наш выбор в общем зачёте — Microsoft. Компания дальше остальных продвинулась от сайта с документацией к документационной платформе: один вход, learning-контент, версии, обратная связь, открытая contributor-модель для части материалов и теперь MCP-доступ для AI-инструментов.
Google мы бы выбрали как ежедневный редакционный эталон. Его guide быстрее остальных превращает абстрактное «пишите понятно» в конкретные решения: где поставить условие, как оформить procedure, что считать prescriptive documentation, как писать для глобальной аудитории и как не потерять доступность в таблице, ссылке или UI-инструкции.
IBM — самый недооценённый участник сравнения. Именно здесь сильнее всего формализовано то, о чём документационные команды обычно спорят на уровне вкуса: качество, типы контента, retrievability, feedback, метрики и обслуживание. Для большой зрелой команды подход IBM полезнее ещё одного красивого style guide.
Apple задаёт направление для developer documentation. DocC показывает, что API reference, conceptual article и tutorial не обязаны жить в разных системах: их можно собирать рядом с кодом, связывать по symbols и доставлять в IDE и web одним процессом. Для продуктовых API-команд это, на наш взгляд, самая перспективная архитектура из четырёх.
Если выбирать одну документационную систему целиком, первое место мы отдаём Microsoft: ни у одной из трёх других компаний нет такого же сочетания портала, learning-контента, версий, feedback и официального машинного доступа. Google выигрывает другой конкурс — его публичный style guide сегодня полезнее всего держать под рукой во время ежедневной редакторской работы. IBM сильнее там, где команде нужно перестать спорить о вкусе и формализовать качество, типы контента, поиск и обслуживание. Apple убедительнее всех показывает будущее developer documentation: документация живёт рядом с кодом, собирается вместе с ним и остаётся частью developer experience. Для зрелой команды лучшая модель складывается из четырёх решений: платформенное мышление Microsoft, редакционная дисциплина Google, модель качества IBM и code-integrated workflow Apple.