![Page 1: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/1.jpg)
![Page 2: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/2.jpg)
Руководство по стилю. Зачем и как
Татьяна Грачёва. Редактор технической документации Третий Гипербатон: Москва, 18 апреля 2015 года
![Page 3: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/3.jpg)
О чём поговорим
1 Зачем нам руководство по стилю
2 Что включать в руководство
3 Как сделать, чтобы руководство работало
![Page 4: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/4.jpg)
Зачем нам руководство по стилю
![Page 5: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/5.jpg)
Три типа руководств
5
Брендбук
Общие рекомендации от отдела текстов
Частные руководства
![Page 6: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/6.jpg)
Три типа руководств
6
Брендбук
Общие рекомендации от отдела текстов
Частные руководства
Логотип
Названия сервисов
Цвета
![Page 7: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/7.jpg)
Три типа руководств
7
Брендбук
Общие рекомендации от отдела текстов
Частные руководства
Единый стиль
Пресс-релизы
Новости
Реклама
Интерфейс
![Page 8: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/8.jpg)
Новость и инструкция
8
Новость
В феврале 2015 года люди задали более 3,5 миллионов запросов о туристических поездках в поиске Яндекса. Это показывает, что спрос на путешествия вполне себе сохраняется. Конечно, люди стали экономить на отдыхе, но пока не отказываются от него полностью, а просчитывают разные варианты и выбирают наиболее выгодный…
Инструкция
Яндекс.Путешествия — это сервис для поиска и покупки туров и для выбора отелей. На сервисе вы можете:
• найти готовые туры или спланировать поездку самостоятельно;
• посмотреть предложения от конкретного туроператора…
![Page 9: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/9.jpg)
Три типа руководств
9
Брендбук
Общие рекомендации от отдела текстов
Частные руководства
Термины
Стиль
Типовые обороты
![Page 10: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/10.jpg)
Пишем в едином стиле
10
Улучшаем качество Экономим время и силы
![Page 11: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/11.jpg)
Что включать в руководство
![Page 12: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/12.jpg)
Единый стиль
12
Пишем коротко и ясно:
› Без сложных конструкций
› В активном залоге
› Без канцеляризмов
› Без причастий и деепричастий
![Page 13: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/13.jpg)
Технические термины
13
С
сайт — (не веб-сайт)
сбой программы — (не крэш программы)
сервер — мн. ч. серверы
сеть — с маленькой буквы
синтаксический анализатор — (не парсер)
сниппет — при первом употреблении с расшифровкой в скобках
страница — (не веб-страница)
сэмплирование — Почему так
![Page 14: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/14.jpg)
Технические термины
14
С
сайт — (не веб-сайт)
сбой программы — (не крэш программы)
сервер — мн. ч. серверы
сеть — с маленькой буквы
синтаксический анализатор — (не парсер)
сниппет — при первом употреблении с расшифровкой в скобках
страница — (не веб-страница)
сэмплирование — Почему так
По правилам транслитерации. Более частотный вариант
![Page 15: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/15.jpg)
Названия продуктов
15
Браузер Yandex
› режим Инкогнито
› режим Турбо
› Табло — на Табло (не в Табло). Почему
› Умная строка
![Page 16: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/16.jpg)
Элементы интерфейса
16
Кнопка Значок
![Page 17: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/17.jpg)
Шаблоны
17
▌ Действия с интерфейсом
▌ Аббревиатуры
▌ Новые термины
▌ Ссылки
![Page 18: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/18.jpg)
Шаблоны. Действия с интерфейсом
18
Элемент Используем Не используем
Значок Нажмите значок Щёлкните на значке. Почему
Кликните по значку. Почему
Кнопка Нажмите кнопку Нажмите на кнопку. Почему
![Page 19: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/19.jpg)
Шпаргалки по языку. Сокращения
19
килобайт КБ
килобит Кбит
килогерц кГц
![Page 20: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/20.jpg)
Загадка. Как расставить запятые?
20
Откройте текстовый редактор (например ? Блокнот).
Откройте текстовый редактор ? например ? Блокнот.
![Page 21: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/21.jpg)
Пунктуация у Розенталя
21
Одни и те же слова могут употребляться то в качестве вводных (стало быть, не членов предложения), то в качестве членов предложения (чаще всего сказуемых или обстоятельств). Ср.: Вы, верно, переведены сюда из России? (Лермонтов). – Вы верно перевели этот отрывок? Цех, возможно, уже реорганизован. – Цех возможно реорганизовать. Синтаксическая роль подобных слов обусловлена контекстом, и проверить ее можно путем изъятия этих слов из состава предложения: в одном случае (без вводного слова) структура
предложения сохраняется (Цех уже реорганизован), в другом (без члена предложения) – чаще всего распадается (Цех... реорганизовать, без интонации побуждения). Однако в некоторых случаях предложения двузначны, и указанный прием проверки не дает нужных результатов: структура предложения сохраняется как при изъятии вводного слова, так и при
изъятии члена предложения. Ср.: Прежде всего нужно говорить именно об этом («сначала»). – Прежде всего, нужно ли говорить именно об этом? (указывается связь мыслей). Он безусловно прав (обстоятельственное слово; указывается степень его правоты). – Он, безусловно, прав (вводное слово; указывается на уверенность в его правоте). Ваши рассуждения естественно подводят нас к правильному решению (естественным образом). – Ваши рассуждения, естественно, подводят нас к правильному решению («разумеется»). Таким образом конфликт был благополучно разрешен («таким способом»). – Таким образом, конфликт был благополучно разрешен («итак»). Далее слово берет председатель профкома («затем»; последовательность фактов). – Далее, слово берет председатель профкома (последовательность изложения мыслей). После обхода больных врач может быть у себя в кабинете («может находиться»). – После обхода больных врач, может быть, у себя в кабинете («возможно»). И потом он стал знаменитым («затем, после этого»). – И, потом, он в моих глазах знаменитость («кроме того»). Не иначе как отец дознался (цельное сочетание «не иначе как»). – Не иначе, кто-нибудь из мальчишек это сделал (вводное сочетание «не иначе» в значении «должно быть»). Ср. также предложения: Правда, хорошо, что он приехал? (правда – вводное слово в значении «не правда ли?»). – Правда, на дискуссию у него ушло много сил, но зато молодежь, участвовавшая в ней, многому
научилась (Н. Островский) (правда – вводное слово в функции уступительного союза). – Мужики... не были убеждены, что сараи теперь и правда стали не их (Солоухин) (правда – частица в значении «действительно»).
Без меня все пропадет, и отец со старухой, гляди, по миру пойдут (Чехов) (гляди – вводное слово в значении «весьма вероятно, очень может быть»). – Он, того и гляди, нагрянет неожиданно (вводное сочетание, указывающее на возможность внезапного действия). Гляди не простудись (гляди – частица при форме повелительного наклонения для выражения предостережения). Хоть и маленький, а гляди как защищается (гляди – частица с усилительным значением).
Он, знаешь, человек обязательный (вводное слово). – А нам за это знаешь что будет? (близко к частице); также: Потом зимы были знаешь какие!; Я нашел на столе знаете что? (знаешь, знаете в значении экспрессивно-усилительной частицы).
Я, видишь, все это уже прошел (вводное слово). – А бабка Варвара, видишь что делает? (в значении экспрессивно-усилительной частицы). В этих случаях, так же, как в предыдущих, слова знаешь, знаете, видишь и т.п. употреблены с ослабленным лексическим значением в результате того, что они оказались внутри предложения, которое по смыслу должно бы от них зависеть; ср.: Знаешь, что нам за это будет? Видишь, что делает бабка Варвара? (см. §107, примеч. 1).
Передайте, пожалуйста, эту рукопись редактору (пожалуйста – вводное слово в значении «прошу вас»). – Скажи пожалуйста, какой храбрец! (цельное сочетание скажи пожалуйста при выражении удивления, возмущения, негодования). – Вечером пожалуйста, а днем прийти не могу (пожалуйста – частица для выражения согласия, в значении «да»).
Слово наконец является вводным, если оно указывает связь мыслей, порядок изложения (в значении «и еще») или дает оценку факта с точки зрения говорящего, например: Да и наконец, всегда лучше впасть в ошибку, думая хорошо (Горький); Да уходите же, наконец! (Чеков). В значении же «под конец», «напоследок», «после всего», «в результате всего» слово наконец не является вводным, например: ...Мы поднимались все выше и выше и наконец достигли вершины горы (Закруткин); ...Быстро ушли все наличные деньги, бриллианты жены, наконец и большая часть приданого дочери (Гончаров).
![Page 22: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/22.jpg)
Пунктуация в шпаргалке
22
Например
Обычно обособляется, как и другие вводные слова:
Откройте любой текстовый редактор (например, Блокнот).
Если например вводит присоединительную конструкцию или стоит в начале или конце обособленного оборота, то он не отделяется от этого оборота запятой:
Откройте любой текстовый редактор, например Блокнот.
![Page 23: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/23.jpg)
Пунктуация в шпаргалке. Схема
23
Обособлять ли «например»?
«Например» стоит возле скобки или после тире?
Запятая нужна Это первое слово в предложении?
Открывает/закрывает уточнение?
Не обособляем
Запятая нужна
Запятая нужна
Да
Да
Да
Нет
Нет
Нет
![Page 24: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/24.jpg)
Как расставить запятые? Отгадка
24
Откройте текстовый редактор (например, Блокнот).
Откройте текстовый редактор, например Блокнот.
![Page 25: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/25.jpg)
Шпаргалки. Гнёзда синонимов
25
Информация
Сведения
Данные
Содержится
Представлен
Приведен
Описан
Перечислены
Выводится
Отображается
Содержится
Учитывается
Включается
Отбирается
Формируется
![Page 26: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/26.jpg)
Шпаргалка. Элементы кода
26
<p align=ʺrightʺ>содержимое</p>
Открывающий тег Закрывающий тег
Название атрибута
Значение атрибута
Атрибут
Имя элемента
Элемент
![Page 27: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/27.jpg)
Как сделать, чтобы руководство работало
![Page 28: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/28.jpg)
Два подхода к созданию руководства
28
Диктат Соборность
![Page 29: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/29.jpg)
Привлекаем команду
29
Задаём вопросы Высказываем точку зрения Консультируемся Приводим аргументы Всё фиксируем
![Page 30: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/30.jpg)
Делаем доступным
Размещаем во внутренней сети Оповещаем и обсуждаем Предлагаем образцы документации
30
![Page 31: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/31.jpg)
Убираем воду
31
В руководстве — только самое важное
![Page 32: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/32.jpg)
Расширяем справочник
32
Шпаргалок может быть много
![Page 33: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/33.jpg)
Структурируем
33
![Page 34: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/34.jpg)
Добавляем инфографику
34
![Page 35: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/35.jpg)
Обновляем
35
Проверяем руководство на актуальность
![Page 36: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/36.jpg)
Контролируем
36
Редактор
Ищет проблемы
Ставит вопросы
Привлекает команду
Пишет руководство Вносит правки
Текст
![Page 37: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/37.jpg)
Что в итоге
![Page 38: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/38.jpg)
Зачем нужно руководство по стилю
38
1. Сохраняет единый стиль документации.
2. Облегчает работу:
писателю редактору переводчику
читателю службе поддержки
![Page 39: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/39.jpg)
Как сделать руководство по стилю лучше
39
Привлекать команду
Структурировать
Сохранять аргументы
Иллюстрировать
Обновлять
![Page 40: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/40.jpg)
Спасибо за внимание!
![Page 41: Руководство по стилю документации: зачем и как, Татьяна Грачёва](https://reader034.vdocuments.net/reader034/viewer/2022042512/55a685fa1a28abe7088b462f/html5/thumbnails/41.jpg)
Контакты
Татьяна Грачёва Редактор технической документации Яндекса
Клуб технических писателей: clubs.ya.ru/x-plain