Update Overview-for-publishing.md

Правка мелких опечаток и запятых + 2 смысловые правки: 1) why API docs failed → в чем ПРИЧИНА провала, а не в чем провал, 2) switching authoring tools → сменить инструмент, а не выбирать ("Том Джонсон сделал это, его компания была стартапом". Здесь "это" - это смена, а не выбор).

Publishing-doc/Overview-for-publishing.md

@@ -1,6 +1,6 @@
 # Обзор вариантов публикации документации
 
-Когда технический писатель ищет способы принести пользу в высокотехнологичной организации, он может обнаружить, что написания технического контента занимает меньшее время, чем его редакция/публикация. Можно вести и управлять публикацией технического контента, который в основном разрабатывают инженеры. По этой причине публикации отведен полноценный модуль на этом курсе о документировании API.
+Когда технический писатель ищет способы принести пользу в высокотехнологичной организации, он может обнаружить, что написание технического контента занимает меньше времени, чем его редакция/публикация. Можно вести и управлять публикацией технического контента, который в основном разрабатывают инженеры. По этой причине публикации отведен полноценный модуль на этом курсе о документировании API.
 
 [Зачем фокусироваться на публикации?](#focus)
 
@@ -21,11 +21,11 @@
 
 Первый вопрос, касающийся публикации документации по API, может быть такой: *почему?* Что делает публикацию API-документации настолько отличной от публикации других видов документации, что она заслуживает отдельного модуля? Как и почему подход с публикацией документов API должен отличаться от подхода публикации обычной документации?
 
-Работая с документацией API мы не находимся в области документации с графическим интерфейсом пользователя (GUI), обычно предназначенной для основных конечных пользователей. Большая часть контента для разработчиков сложна и требует опыта не только в программировании, но и в конкретном языке программирования или среде.
+Работая с документацией API, мы не находимся в области документации с графическим интерфейсом пользователя (GUI), обычно предназначенной для основных конечных пользователей. Большая часть контента для разработчиков сложна и требует опыта не только в программировании, но и в конкретном языке программирования или среде.
 
 Так, технический писатель, может обнаружить, что все слишком сложно и будет полагаться на разработчиков, которые пишут больше контента. Закачивается все тем, что техписатель играет роль инструмента документооборота и рабочего процесса.
 
-В статье [Как проваливается документация API](https://ieeexplore.ieee.org/document/7140676) (опубликовано в [IEEE Software](https://ieeexplore.ieee.org/Xplore/home.jsp)), Мартин Робиллард и Гиас Уддин опросили разработчиков, чтобы выяснить, в чем провал API документации для них. Было обнаружено, что большинство недостатков были связаны с содержанием: неполное, неточное, отсутствует, неоднозначное, фрагментированное и т. Д. Они суммировали свои выводы здесь:
+В статье [Как проваливается документация API](https://ieeexplore.ieee.org/document/7140676) (опубликовано в [IEEE Software](https://ieeexplore.ieee.org/Xplore/home.jsp)) Мартин Робиллард и Гиас Уддин опросили разработчиков, чтобы выяснить, в чем причина провала API документации для них. Было обнаружено, что большинство недостатков были связаны с содержанием: неполное, неточное, отсутствует, неоднозначное, фрагментированное и т. Д. Они суммировали свои выводы здесь:
 
 ![result](pics/23.png)
 > Причины провала документации
@@ -63,9 +63,9 @@
 <a name="dismatch"></a>
 ### 1. Инструменты HAT (Help Authoring Tool) не соответствуют рабочим процессам и средам разработчиков
 
-Если разработчики собираются внести свой вклад в документацию (или написать документ полностью самостоятельно), инструменты должны соответствовать их собственным рабочим процессам. Их инструментарий состоит в том, чтобы рассматривать документ как код, связывать его с контролем версий, создавать выходные данные с сервера и т. Д. Они хотят упаковать документацию вместе с другим кодом, проверить ее в своих репозиториях и автоматизировать как часть процесса сборки. Если разработчики вносят свой вклад в документацию, тем писателям, которые используют HAT будет сложно.
+Если разработчики собираются внести свой вклад в документацию (или написать документ полностью самостоятельно), инструменты должны соответствовать их собственным рабочим процессам. Их инструментарий состоит в том, чтобы рассматривать документ как код, связывать его с контролем версий, создавать выходные данные с сервера и т. Д. Они хотят упаковать документацию вместе с другим кодом, проверить ее в своих репозиториях и автоматизировать как часть процесса сборки. Если разработчики вносят свой вклад в документацию, тем писателям, которые используют HAT, будет сложно.
 
-В добавок, практически нет такого HAT. который работает на Mac. Многие разработчики и дизайнеры предпочитают Mac, потому что у них гораздо лучшая платформа разработки (например, командная строка намного удобнее и функциональнее). Для любителей Windows, могут быть сложности при установке инструментов разработчика или следовании справочникам по настройке и тестировании контент.
+В добавок, практически нет такого HAT, который работает на Mac. Многие разработчики и дизайнеры предпочитают Mac, потому что у них гораздо лучшая платформа разработки (например, командная строка намного удобнее и функциональнее). Для любителей Windows могут быть сложности при установке инструментов разработчика или следовании справочникам по настройке и тестировании контента.
 
 А если заставить разработчиков использовать HAT, нужно покупать лицензию для каждого участвующего разработчика. Напротив, инструменты «docs-as-code» часто имеют открытый исходный код и поэтому могут масштабироваться по всей компании без бюджетного финансирования и утверждения.
 
@@ -81,7 +81,7 @@
 
 Разработчики часто хотят поместить адресную документацию для API в четко определенные шаблоны, которые содержат такие разделы, как параметры конечных точек, примеры запросов, примеры ответов и т. Д. (Список разделов изучали в модуле [Документировании конечных точек API](../documenting-api-endpoints/README.md) )
 
-При наличии большого количества конечных точек, нужна система для загрузки контента в стандартные шаблоны. В идеале надо разделять различные разделы (описание, параметры, ответы и т. Д.), А затем компилировать информацию через шаблон при создании сайта. Или можно использовать спецификацию, такую ​​как [OpenAPI](../openAPI-specification/introduction-openapi-and-swagger.md), чтобы добавить информацию в шаблон. Можно включать также пользовательские сценарии. Тем не менее, такие опции часто отсутствуют в HAT, из-за ограничений наличия рабочих процессов и шаблонов, поддерживаемых «из коробки».
+При наличии большого количества конечных точек, нужна система для загрузки контента в стандартные шаблоны. В идеале надо разделять различные разделы (описание, параметры, ответы и т. д.), а затем компилировать информацию через шаблон при создании сайта. Или можно использовать спецификацию, такую ​​как [OpenAPI](../openAPI-specification/introduction-openapi-and-swagger.md), чтобы добавить информацию в шаблон. Можно включать также пользовательские сценарии. Тем не менее, такие опции часто отсутствуют в HAT из-за ограничений наличия рабочих процессов и шаблонов, поддерживаемых «из коробки».
 
 <a name="consoles"></a>
 ### 4. Многие API имеют интерактивные консоли, позволяющие осуществлять запросы
@@ -100,7 +100,7 @@
 
 В документации API часто документация является интерфейсом продукта - нет отдельного GUI продукта (графический пользовательский интерфейс), с которым взаимодействуют клиенты. Поскольку графический интерфейс продукта - это документация, он должен быть привлекательным и сексуальным.
 
-Большинство справок Tripane не выглядит так. Если справка выглядит старой и основанной на фреймах, она не внушает особого доверия разработчикам в ее оценке.
+Большинство справок Tripane не выглядит так. Если справка выглядит старой и основанной на фреймах, она не внушает особого доверия разработчикам при ее оценке.
 
 В последнем выпуске Flare довольно много настроек отображения, возможно, это поможет закончить внешний вид устаревшего вывода Tripane. Тем не менее, усилия и процесс создания выходных данных для HAT обычно кардинально отличаются от настройки выходных данных генератора статичных сайтов. Веб-разработчикам будет гораздо удобнее с последним.
 
@@ -109,7 +109,7 @@
 
 Основываясь на всех этих факторах, Том Джонсон решил приостановить работать в DITA и попробовать новый инструмент для документации: [Jekyll](Jekyll-and-cloudCannon.md#about). Jekyll позволяет работать с Markdown, использовать Liquid для условной логики и инициировать сборки непосредственно из репозитория.
 
-Понятно, что не у всех есть возможность выбирать средства разработки, но когда Том Джонсон сделал это, его компания была стартапом, и было всего три писателя с минимальным количеством устаревшего контента. Том не был обременен кучей долгов документации или обременительными процессами, поэтому я мог вводить новшества.
+Понятно, что не у всех есть возможность сменить средство разработки, но когда Том Джонсон сделал это, его компания была стартапом, и было всего три писателя с минимальным количеством устаревшего контента. Том не был обременен кучей долгов документации или обременительными процессами, поэтому я мог вводить новшества.
 
 Jekyll - это всего лишь один из вариантов публикации документации в пространстве документации API. Хорошо работать с подходом Jekyll, [основанным на коде](Doc-as-code-tools.md), но есть [много разных инструментов](Static-site-generators.md) и [опций публикации](Hosting-and-deployment-options.md). Все это мы изучим в этом модуле.