Технический писатель: быстрое погружение

Программа обучения

• Ознакомительный урок. "Что такое техническое документирование и каким оно может быть"4 акад. часа

  1.1 #whoami кто я? Краткий рассказ о себе и о своих профессиональных компетенциях.

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

  1.3 Знакомьтесь с миром документов: три грани документации. Как использовать документацию как средство управления процессами (инструмент). Какие подпроцессы включает в себя процесс документирования и для чего он нужен. Что такое документация как продукт и зачем она нужна:

  1.3.1 Документация как инструмент;

  1.3.2 Документация как процесс;

  1.3.3 Документация как продукт.

  1.4 Техническая документация: расставим все точки над i. Что такое техническая документация? Формирование представления о технической документации через сравнение ее с художественными текстами. Определение технической документации и получение представления о том, какия типы технической документации существуют. Какое место занимает документация в разработке ПО? Этапы документирования при разработке ПО. Как отличить техническую документацию от похожей на нее, но не являющейся таковой. Проблемы некорректного набора материала для технической документации. Главный признак тех. документации. Как избежать написания документации ради документации. Свойства документации:

  1.4.1 Искусство ясности в мире технологий;

  1.4.2 Техническая документация в разработке программного обеспечения: зачем она нужна и какая бывает;

  1.4.3 Лжетехническая документация: как не ошибиться?

  1.4.4 Документация ради документации: не надо так.

  1.5 Загадочные документоведы и где они обитают. Специалисты, работающие с техническими текстами. Кто такой технический писатель, какие его роли и задачи на рабочем месте? Где проходит граница компетенций техписателя? Кто еще занимается разработкой технической документации? Локализаторы, редакторы, переводчики, аналитики. Чем эти специалисты отличаются от техписателей:

  1.5.1 Технический писатель: кто такой, что делает и зачем нужен компаниям?

  1.5.2 Не только техписы: кто еще превращает текстовый хаос в структуру?

  1.6 Разбор текущей ситуации на рынке труда. Оценка востребованности профессии техписателя. Как найти работу техписателем, которая не разорчарует? Что может скрываться под вакансией «Технический писатель»? Какие хард и сорф компетенции работодатели ждут от потенциального кандидата:

  1.6.1 Работа техническим писателем и «техническим писателем»;

  1.6.2 Обзор типичных ожиданий от кандидата;

  1.7 Техписатель VS AI: как быть незаменимым. Какими компетенциями надо обладать, чтобы не быть замененным искусственным интеллектом?

• Блок 1. Искусство технического документирования: от концепции до реализации. Уроки 2-10

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

• Урок 2. Особенности технического текста4 акад. часа

  2.1 Основы философии технического документирования. Какие особенности формируют принципы технического текста:

  2.1.1 Принцип единообразия: аналогичное описывай аналогично. Как соблюдать принцип единообразия? Рассмотрение примеров и выполнение практических заданий на уроке.

  2.1.2 Принцип ясности: пользователю этот текст абсолютно понятен. Как соблюдать принцип ясности? Рассмотрение примеров и выполнение практических заданий на уроке.

  2.1.3 Принцип полноты: документация - самодостаточный источник. Как соблюдать принцип полноты? Какие бывают нарушения принципа полноты? Рассмотрение примеров и выполнение практических заданий на уроке.

  2.1.4 Принцип точности: нет ошибкам и неоднозначности. Как соблюдать принцип точности? Рассмотрение примеров и выполнение практических заданий на уроке.

  2.1.5 Принцип краткости: сокращаем без потерь. Как писать кратко, не нарушая другие принципы? Рассмотрение примеров и выполнение практических заданий на уроке.

  2.1.6 Принцип объективности: нет авторской мысли. Как соблюдать принцип объективности? Рассмотрение примеров и выполнение практических заданий на уроке.

  2.2 Глоссарии и стайлгайды: ключи к единообразию и пониманию. Как сформировались принципы технического текста? Как развилась концепция стайлгайда:

  2.2.1 Что такое стайлгайд и какие проблемы он решает? Рассмотрение примеров стайлгайдов. Концепция стайлгайдов за рубежом и в России: в чем сходства и отличия. Что включает типичный стайлгайд?

  2.2.2 Что такое глоссарий и какая его цель? Обязательные и необязательные элементы глоссария. Выполнение практических заданий на уроке.

• Урок 3. Стиль и манера изложения в техническом документе5 акад. часа

  3.1 Определения стиля и манеры изложения. В чем разница между стилем и манерой изложения? Что такое голос бренда? 

  3.2 Стиль как способ выражения технической мысли: составляющие стиля. Как формируется манера изложения в рамках технического стиля и какой набор характеристик включает: 

  3.2.1 Тон и уровень формальности: обращение к пользователю и этикетные требования. Что такое тон? Формальный тон в техническом тексте. Как формируется формальный тон изложения? Характеристики формального тона. Слова, выражения и словосочетания. Термины. Обращение к пользователю. Этикет в техническом документе. Характеристики этикетных требований. Рассмотрение примеров. 

  3.2.2 Лексика: проблемы и пути решения. Что такое лексика? Какие проблемы могут быть связаны с лексикой при написании технической документации и как их решить? Рассмотрение практических примеров и выполнения задания. 

  3.2.3 Стилистические приемы: допустимые и недопустимые. Что такое стилистические приемы? Недопустимые приемы в техдокументации. Антропоморфизм. Допустимые приемы в техдокументации. Клише. Однородные члены. Повтор. Цитаты. Параллельные и присоединительные конструкции. Рассмотрение практических примеров и выполнение заданий. 

  3.2.4 Синтаксис: какой порядок слов в предложении? Как строить предложения в техническом тексте? Прямой порядок слов. Рекомендации по использованию синтаксических конструкций. 

  3.2.5 Морфология: как использовать совершенный и несовершенный вид глагола в техническом документе. Рассмотрение примеров.

  3.2.6 Форматирование: как выделять значимый текст? Что такое форматирование? Понятие значимого текста. Рассмотрение примеров и выполнение задания. 

• Урок 4. Элементы технического документа5 акад. часа

  4.1 Заголовки:

  4.1.1 Рекомендации по созданию заголовков. Рекомендации по смысловой нагрузке и оформлению заголовков. Виды заголовков. Подзаголовки. Втянутые заголовки в списках.

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

  4.2 Примеры, виды примеров. Как оформлять примеры? Краткий и развернутый примеры. Разбор примеров и выполнение заданий:

  4.2.1 Краткий пример; 

  4.2.2 Развернутый пример. 

  4.3 Информационные блоки. Как предупреждать об опасных действиях? Как описывать дополнительную информацию нейтрального или положительного содержания? Как оформлять информационные блоки?  Разбор примеров и выполнение заданий: 

  4.3.1 Предупреждаем об опасных последствиях; 

  4.3.2 Подсвечиваем важные положительные моменты;

  4.4 Сноски: цели и логика. Что такое сноски? Когда и как использовать сноски?

  4.5 Списки: виды и оформление:

  4.5.1 Виды списков. Список со втянутыми заголовками. Структурированный и неструктурированный списки. Виды структурированных списков. Маркированный и нумерованный список.

  4.5.2 Рекомендацию по оформлению списков. Титульная фраза. Пункты. Разбор примеров.

  4.6 Таблицы:

  4.6.1 Элементы таблицы. Название. Столбцы. Строки. Ячейки. Наполнение ячеек.

  4.6.2 Рекомендации по оформлению таблиц. Общие рекомендации. Выравнивание и выделение текста. Единицы измерения в таблице. Разбор примеров.

  4.7 Иллюстрации:

  4.7.1 Виды иллюстраций. Снимки экрана. Схемы. Картинки. "Гифки". Видео. 

  4.7.2 Рекомендации по использованию иллюстраций. Принципы использования иллюстраций. Оформление иллюстраций. Разбор примеров.

• Урок 5. Организация информации: создание структуры технического документа5 акад. часа

  5.1 Логика изложения: 

  5.1.1 Принципы логики изложения и организации информации. Разбор следующих принципов: сначала общее — затем частное; сначала простое — затем сложное; сначала известное — затем новое; сначала «что делать» — затем «как делать».

  5.1.2 Популярные ошибки нарушения логики. Разбор ошибок на примерах.

  5.1.3 Дублирование информации. Плюсы и минусы дублирования. Как избежать дублирования?

  5.2 Типы организации информации. Разбор типов с примерами:

  5.2.1 Описание. Типы и цели описания. Конструирование описания. Описание предмета. Описание причин. Описание следствий. Описание процесса.

  5.2.2 Классификация. Определение и цель классификации. Конструирование классификации. 

  5.2.3 Определение. Типы и цель определений. Явное и неявное определение. Краткое и развернутое определение. Конструирование определений.

  5.2.4 Сравнение. Определение и цель сравнения. Конструирование сравнений.

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

  5.3.1 Раздел-введение. Цель введения. Как писать в введение? Типы организации информации во введении. 

  5.3.2 Раздел-статья. Цель статьи. Как писать статью? Типы организации информации в статье.

  5.3.3 Раздел-инструкция. Цель инструкции. Общая информация об инструкциях. Вариации инструкций. Типы организации информации в инструкции.

  5.3.4 Раздел с описанием новых возможностей. Цель "релиз-нотсов". Отличия описания новых возможностей от других типов разделов. Как писать "релиз-нотсы"?

• Урок 6. Целеполагание и этапы создания контента4 акад. часа

  6.1 Кому мы пишем: портрет пользователей. Какая потенциальная аудитория у технических документов? Технические специалисты. Разработчики. Системные администраторы. Пользователи без специальных знаний в сфере информационных технологий.

  6.2 Зачем мы пишем: сценарии использования материалов. Сценарий поиска сведений об установке и настройке. Сценарий поверхностного ознакомления с продуктом: начало работы и решение типичных простых задач. Сценарий целевого поиска решения конкретной задачи. Сценарий целевого поиска справочной информации по функции или элементу интерфейса. Сценарий поиска трактовки специальных терминов. 

  6.3 Что мы пишем: два основных вида представления материала:

  6.3.1 Справочники и руководства: комплектации пользовательской документации. Цели руководства. Что может входить в руководство? Цели справочника. Что может входить в справочник?

  6.3.2 UX-текст: роль техписателя в разработке интерфейса. Что такое интуитивный интерфейс. Что такое вычитка интерфейсных текстов и зачем она нужна?

  6.4 Этапы создания контента: алгоритм действий. Поэтапный разбор процесса разработки документации на примере реальных задач: как понять, куда и что нужно писать? Как определить аудиторию? Как определить границы описания? Как определить источник размещения информации?

• Урок 7. Разработка контента для справочников и руководств5 акад. часа

  7.1 Пишем пошаговые инструкции. Разбор материала, примеров и выполнение заданий:

  7.1.1 Заголовок. Цель заголовка инструкции. Рекомендации к заголовкам инструкций. Разбор примеров и выполнение заданий.

  7.1.2 Вводный текст. Цель вводного текста инструкции. Рекомендации к вводному тексту инструкции. Разбор примеров и выполнение заданий.

  7.1.3 Титульная фраза. Цель титульной фразы. Разбор примеров и выполнение заданий.

  7.1.4 Шаги. Правила к шагам инструкции. Рекомендации к формулировкам шагов. Как прописывать условные шаги? Разбор примеров и выполнение заданий.

  7.1.5 Пояснения к шагам. Цель пояснений к шагам. Когда использовать пояснения? Рекомендации к пояснениям. Разбор примеров и выполнение заданий.

  7.1.6 Иллюстрации. Когда инструкциям нужны иллюстрации? Разбор примеров и выполнение заданий.

  7.1.7 Заключение. Цель заключения. Когда нужно заключение? Формулировка заключения к шагам инструкции. Разбор примеров и выполнение заданий.

• Урок 8. UX-писательство: повышаем интуитивность интерфейса5 акад. часа

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

  8.2 Из чего состоит интерфейс? Распространенные элементы интерфейса: кнопка, кнопка переключения, вкладка, всплывающая подсказка, значок, список, строка состояния, меню, окно, блок параметров, панель инструментов, ползунок, полоса прокрутки, поле ввода, поле поиска, поле для загрузки файла, "чекбокс", радиокнопка. 

  8.3 Пишем тексты сообщений программы:

  8.3.1 Типы сообщений программы: сообщение о результате действия, сообщение об ошибке, предупреждение о возможной проблеме,  уведомление, запросы на подтверждение действия. 

  8.3.2 Сообщение об ошибке: не напугай пользователя. Роль сообщения об ошибке. Смысловые части сообщения об ошибке. Контексты ошибок. Вежливость в сообщении об ошибке. Лексика в сообщении об ошибке. Графика в сообщении об ошибке. Рассмотрение примеров и выполнение задания. 

  8.3.3 Запрос на подтверждение действия: да нет наверное. Роль запроса на подтверждение действия. Функции запроса на подтверждение действия. Структура запроса на подтверждение действия: заголовок окна, текст, кнопка подтверждения действия. Как называть запрос на подтверждение действия в документации? Рассмотрение примеров и выполнение задания. 

  8.3.4 Всплывающая подсказка. Роль всплывающей подсказки. Контекст использования всплывающей подсказки. Стилистические приемы для всплывающей подсказки. Как называть всплывающую подсказку в документации? Рассмотрение примеров и выполнение задания. 

• Урок 9. Большая совместная практическая работа: вычитка с дизайнером4 акад.часа

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

• Урок 10. Инструменты документирования: как и где ведется работа?4 акад.часа

  10.1 Подход Docs-as-code. Что это такое? Языки разметки и их практическое применение. Как ведется работа с Git. Преимущества Docs-as-code. 

  10.2 Вики-системы. Что такое вики-система? Функции вики-систем. Плюсы и минусы использования. Примеры вики-систем. 

  10.3 СCMS: системы управления компонентным контентом. Понятие CCMS. Преимущества использования CCMS. Примеры CCMS. 

  10.4 Swagger. Что это такое? Как Swagger помогает техписателю в описании API.

• Блок 2. IT база для технического писательства. Уроки 11-15

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

• Урок 11. Технические знания для техписателя: расставим точки над i4 акад. часа

  11.1 Писать о коде, не будучи программистом: где проходит граница компетенций?

  11.1.1 Реальные примеры запросов работодателей. Рассматриваем на примере скриншотов из hh.ru, какие технические знания и навыки работодатели ожидают от потенциальных кандидатов на техписателя. 

  11.1.2 Что говорят в комьюнити? Рассматриваем различные точки зрения коллег. Что точно будет плюсом?

  11.1.3 Как быть? Фиксируем выводы. 

  11.2 Практика перевода с программистского на человеческий: приводятся реальные реплики разработчиков/тестировщиков/инженеров, и преподаватель помогает разобраться со смыслом фраз, а также дает рекомендации, как работать с профессиональным сленгом.

• Урок 12. Техписательство в эпоху киберугроз: пишем безопасно4 акад. часа

  12.1 Принципы информационной безопасности, соблюдаемые при написании документации: конфиденциальность, целостность, доступность. Угрозы информационной безопасности. Факторы угроз. Внешние и внутренние угрозы. 

  12.2 Чувствительная информация в тексте. Как безопасно писать: примеры. Логин и пароль в документации. Почтовые и IP адреса. Доменные имена. Как описывать работу со сторонним ПО?

  12.3 Информационная гигиена. 

• Урок 13. API - это база4 акад. часа

  13.1 Что такое API, зачем его используют и как оно работает? Зачем техписателю знать базовые понятия API?

  13.1.1 Определение API. Публичные и непубличные API.

  13.1.2 Добро пожаловать в API-ресторан. Как работает API на примере аналогии с рестораном. Понятие фронтенда и бэкенда. 

  13.2.3 Методы API. Запрос и ответ. Основные методы API. Выполнение задания.

• Урок 14. Документируем API4 акад. часа

  14.1 Примеры документированных API. Примеры публичных описаний API.

  14.2 Как описывается API: примеры и рекомендации. Возможная структура документа с описанием запроса. Понятие "эндпоинта" и URL. Как описывается "эндпоинт": метод и URL запроса. Как описываются параметры запроса? Как описываются параметры ответа? Статус, коды ошибок. Шаблон структуры с примером. Выполнение задания.

• Урок 15. Заключение курса4 акад. часа

  15.1 Подводим итоги: какие навыки мы обрели и что делать дальше? Ответы на вопросы слушателей. 

  15.2 Написание резюме по освоенной профессии технического писателя совместо с педагогом. 

  15.3 Получение бонусной методички с полезными материалами для повторения. 

• Зачет3 акад. часа