Руководство по стилю документации: зачем и как,...

Руководство по стилю. Зачем и как

Татьяна Грачёва. Редактор технической документации Третий Гипербатон: Москва, 18 апреля 2015 года

О чём поговорим

1 Зачем нам руководство по стилю

2 Что включать в руководство

3 Как сделать, чтобы руководство работало

Зачем нам руководство по стилю

Три типа руководств

5

Брендбук

Общие рекомендации от отдела текстов

Частные руководства

Три типа руководств

6

Брендбук

Общие рекомендации от отдела текстов

Частные руководства

Логотип

Названия сервисов

Цвета

Три типа руководств

7

Брендбук

Общие рекомендации от отдела текстов

Частные руководства

Единый стиль

Пресс-релизы

Новости

Реклама

Интерфейс

Новость и инструкция

8

Новость

В феврале 2015 года люди задали более 3,5 миллионов запросов о туристических поездках в поиске Яндекса. Это показывает, что спрос на путешествия вполне себе сохраняется. Конечно, люди стали экономить на отдыхе, но пока не отказываются от него полностью, а просчитывают разные варианты и выбирают наиболее выгодный… 

Инструкция

Яндекс.Путешествия — это сервис для поиска и покупки туров и для выбора отелей. На сервисе вы можете:

•  найти готовые туры или спланировать поездку самостоятельно;

•  посмотреть предложения от конкретного туроператора…

Три типа руководств

9

Брендбук

Общие рекомендации от отдела текстов

Частные руководства

Термины

Стиль

Типовые обороты

Пишем в едином стиле

10

Улучшаем качество Экономим время и силы

Что включать в руководство

Единый стиль

12

Пишем коротко и ясно:

›  Без сложных конструкций

›  В активном залоге

›  Без канцеляризмов

›  Без причастий и деепричастий

Технические термины

13

С

сайт — (не веб-сайт)

сбой программы — (не крэш программы)

сервер — мн. ч. серверы

сеть — с маленькой буквы

синтаксический анализатор — (не парсер)

сниппет — при первом употреблении с расшифровкой в скобках

страница — (не веб-страница)

сэмплирование — Почему так

Технические термины

14

С

сайт — (не веб-сайт)

сбой программы — (не крэш программы)

сервер — мн. ч. серверы

сеть — с маленькой буквы

синтаксический анализатор — (не парсер)

сниппет — при первом употреблении с расшифровкой в скобках

страница — (не веб-страница)

сэмплирование — Почему так

По правилам транслитерации. Более частотный вариант

Названия продуктов

15

Браузер Yandex

›  режим Инкогнито

›  режим Турбо

›  Табло — на Табло (не в Табло). Почему

›  Умная строка

Элементы интерфейса

16

Кнопка Значок

Шаблоны

17

▌ Действия с интерфейсом

▌ Аббревиатуры

▌ Новые термины

▌  Ссылки

Шаблоны. Действия с интерфейсом

18

Элемент Используем Не используем

Значок Нажмите значок Щёлкните на значке. Почему

Кликните по значку. Почему

Кнопка Нажмите кнопку Нажмите на кнопку. Почему

Шпаргалки по языку. Сокращения

19

килобайт КБ

килобит Кбит

килогерц кГц

Загадка. Как расставить запятые?

20

Откройте текстовый редактор (например ? Блокнот).

Откройте текстовый редактор ? например ? Блокнот.

Пунктуация у Розенталя

21

Одни и те же слова могут употребляться то в качестве вводных (стало быть, не членов предложения), то в качестве членов предложения (чаще всего сказуемых или обстоятельств). Ср.: Вы, верно, переведены сюда из России? (Лермонтов). – Вы верно перевели этот отрывок? Цех, возможно, уже реорганизован. – Цех возможно реорганизовать. Синтаксическая роль подобных слов обусловлена контекстом, и проверить ее можно путем изъятия этих слов из состава предложения: в одном случае (без вводного слова) структура

предложения сохраняется (Цех уже реорганизован), в другом (без члена предложения) – чаще всего распадается (Цех... реорганизовать, без интонации побуждения). Однако в некоторых случаях предложения двузначны, и указанный прием проверки не дает нужных результатов: структура предложения сохраняется как при изъятии вводного слова, так и при

изъятии члена предложения. Ср.: Прежде всего нужно говорить именно об этом («сначала»). – Прежде всего, нужно ли говорить именно об этом? (указывается связь мыслей). Он безусловно прав (обстоятельственное слово; указывается степень его правоты). – Он, безусловно, прав (вводное слово; указывается на уверенность в его правоте). Ваши рассуждения естественно подводят нас к правильному решению (естественным образом). – Ваши рассуждения, естественно, подводят нас к правильному решению («разумеется»). Таким образом конфликт был благополучно разрешен («таким способом»). – Таким образом, конфликт был благополучно разрешен («итак»). Далее слово берет председатель профкома («затем»; последовательность фактов). – Далее, слово берет председатель профкома (последовательность изложения мыслей). После обхода больных врач может быть у себя в кабинете («может находиться»). – После обхода больных врач, может быть, у себя в кабинете («возможно»). И потом он стал знаменитым («затем, после этого»). – И, потом, он в моих глазах знаменитость («кроме того»). Не иначе как отец дознался (цельное сочетание «не иначе как»). – Не иначе, кто-нибудь из мальчишек это сделал (вводное сочетание «не иначе» в значении «должно быть»). Ср. также предложения: Правда, хорошо, что он приехал? (правда – вводное слово в значении «не правда ли?»). – Правда, на дискуссию у него ушло много сил, но зато молодежь, участвовавшая в ней, многому

научилась (Н. Островский) (правда – вводное слово в функции уступительного союза). – Мужики... не были убеждены, что сараи теперь и правда стали не их (Солоухин) (правда – частица в значении «действительно»).

Без меня все пропадет, и отец со старухой, гляди, по миру пойдут (Чехов) (гляди – вводное слово в значении «весьма вероятно, очень может быть»). – Он, того и гляди, нагрянет неожиданно (вводное сочетание, указывающее на возможность внезапного действия). Гляди не простудись (гляди – частица при форме повелительного наклонения для выражения предостережения). Хоть и маленький, а гляди как защищается (гляди – частица с усилительным значением).

Он, знаешь, человек обязательный (вводное слово). – А нам за это знаешь что будет? (близко к частице); также: Потом зимы были знаешь какие!; Я нашел на столе знаете что? (знаешь, знаете в значении экспрессивно-усилительной частицы).

Я, видишь, все это уже прошел (вводное слово). – А бабка Варвара, видишь что делает? (в значении экспрессивно-усилительной частицы). В этих случаях, так же, как в предыдущих, слова знаешь, знаете, видишь и т.п. употреблены с ослабленным лексическим значением в результате того, что они оказались внутри предложения, которое по смыслу должно бы от них зависеть; ср.: Знаешь, что нам за это будет? Видишь, что делает бабка Варвара? (см. §107, примеч. 1).

Передайте, пожалуйста, эту рукопись редактору (пожалуйста – вводное слово в значении «прошу вас»). – Скажи пожалуйста, какой храбрец! (цельное сочетание скажи пожалуйста при выражении удивления, возмущения, негодования). – Вечером пожалуйста, а днем прийти не могу (пожалуйста – частица для выражения согласия, в значении «да»).

Слово наконец является вводным, если оно указывает связь мыслей, порядок изложения (в значении «и еще») или дает оценку факта с точки зрения говорящего, например: Да и наконец, всегда лучше впасть в ошибку, думая хорошо (Горький); Да уходите же, наконец! (Чеков). В значении же «под конец», «напоследок», «после всего», «в результате всего» слово наконец не является вводным, например: ...Мы поднимались все выше и выше и наконец достигли вершины горы (Закруткин); ...Быстро ушли все наличные деньги, бриллианты жены, наконец и большая часть приданого дочери (Гончаров).

Пунктуация в шпаргалке

22

Например

Обычно обособляется, как и другие вводные слова:

Откройте любой текстовый редактор (например, Блокнот).

Если например вводит присоединительную конструкцию или стоит в начале или конце обособленного оборота, то он не отделяется от этого оборота запятой:

Откройте любой текстовый редактор, например Блокнот.

Пунктуация в шпаргалке. Схема

23

Обособлять ли «например»?

«Например» стоит возле скобки или после тире?

Запятая нужна Это первое слово в предложении?

Открывает/закрывает уточнение?

Не обособляем

Запятая нужна

Запятая нужна

Да

Да

Да

Нет

Нет

Нет

Как расставить запятые? Отгадка

24

Откройте текстовый редактор (например, Блокнот).

Откройте текстовый редактор, например Блокнот.

Шпаргалки. Гнёзда синонимов

25

Информация

Сведения

Данные

Содержится

Представлен

Приведен

Описан

Перечислены

Выводится

Отображается

Содержится

Учитывается

Включается

Отбирается

Формируется

Шпаргалка. Элементы кода

26

<p align=ʺrightʺ>содержимое</p>

Открывающий тег Закрывающий тег

Название атрибута

Значение атрибута

Атрибут

Имя элемента

Элемент

Как сделать, чтобы руководство работало

Два подхода к созданию руководства

28

Диктат Соборность

Привлекаем команду

29

Задаём вопросы Высказываем точку зрения Консультируемся Приводим аргументы Всё фиксируем

Делаем доступным

Размещаем во внутренней сети Оповещаем и обсуждаем Предлагаем образцы документации

30

Убираем воду

31

В руководстве — только самое важное

Расширяем справочник

32

Шпаргалок может быть много

Структурируем

33

Добавляем инфографику

34

Обновляем

35

Проверяем руководство на актуальность

Контролируем

36

Редактор

Ищет проблемы

Ставит вопросы

Привлекает команду

Пишет руководство Вносит правки

Текст

Что в итоге

Зачем нужно руководство по стилю

38

1.  Сохраняет единый стиль документации.

2.  Облегчает работу:

писателю редактору переводчику

читателю службе поддержки

Как сделать руководство по стилю лучше

39

Привлекать команду

Структурировать

Сохранять аргументы

Иллюстрировать

Обновлять

Спасибо за внимание!

Контакты

t-gracheva@yandex-team.ru

Татьяна Грачёва Редактор технической документации Яндекса

Клуб технических писателей: clubs.ya.ru/x-plain