18 марта 2014. Я.Студент в ВШЭ Кирилл Маслинский. Я. Технический писатель.

1. ........ ............................................................ .... ..... ........ .

2. .
Я.Технический писатель
Кирилл Маслинский
maslinsky@yandex-team.ru
ведущий разработчик технической документации
Яндекс, Санкт-Петербург
18.03.2014 / Я.Студент Москва
........ ............................................................ .... ..... ........ .

3. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Outline
Профессия — технический писатель
Немного истории
Профессиональная идентичность
Документация в IT
Писатель и компания
Документирование в Яндексе
Кто мы
О чем мы пишем
Как мы работаем
Разбираемся
Пишем
Оцениваем результат
3 / 41

4. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
План
Профессия — технический писатель
Немного истории
Профессиональная идентичность
Документация в IT
Писатель и компания
Документирование в Яндексе
Кто мы
О чем мы пишем
Как мы работаем
Разбираемся
Пишем
Оцениваем результат
4 / 41

5. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Истоки
• «Трактат об астролябии»
Чосера (1387?)
• Индустриализация
(руководства к швейным
машинам, велосипедам
и т. п.)
• Первая/Вторая мировая
война (оформление
отдельной профессии)
5 / 41

6. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Истоки
• «Трактат об астролябии»
Чосера (1387?)
• Индустриализация
(руководства к швейным
машинам, велосипедам
и т. п.)
• Первая/Вторая мировая
война (оформление
отдельной профессии)
5 / 41

7. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Истоки
• «Трактат об астролябии»
Чосера (1387?)
• Индустриализация
(руководства к швейным
машинам, велосипедам
и т. п.)
• Первая/Вторая мировая
война (оформление
отдельной профессии)
5 / 41

8. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Профессионалы и любители
technical communication
Bell, I. T. (1890). Bicycling for women
Ward, M. E. (1896). Bicycling for ladies
Sarah Hallenbeck (2012) User Agency, Technical Communication, and the
19th-Century Woman Bicyclist, Technical Communication Quarterly, 21:4, 290-306
6 / 41

9. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Новые жанры документов
7 / 41

10. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Разделение труда
Кто писал документацию:
• специально нанятые журналисты
• сами инженеры
• профессиональные техписатели
8 / 41

11. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
План
Профессия — технический писатель
Немного истории
Профессиональная идентичность
Документация в IT
Писатель и компания
Документирование в Яндексе
Кто мы
О чем мы пишем
Как мы работаем
Разбираемся
Пишем
Оцениваем результат
9 / 41

12. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Сущность профессии по Israel Light
Israel Light
“Technical writing and professional
status” (1961)
• технический писатель как
переводчик
риторика умение писать и владение
жанрами технических текстов
анализ серьезная научная подготовка
визуализация дизайн документов и техническая
графика
10 / 41

13. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Сущность профессии по Israel Light
Israel Light
“Technical writing and professional
status” (1961)
• технический писатель как
переводчик
риторика умение писать и владение
жанрами технических текстов
анализ серьезная научная подготовка
визуализация дизайн документов и техническая
графика
10 / 41

14. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Карьерные траектории
Israel Light, 1961
It is the author’s conviction that those who can write are easily
identified early in their academic life. In order to be useful, however,
they must know something about what to write.
• техническое образование + умение писать
• гуманитарное образование + технические знания
11 / 41

15. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
План
Профессия — технический писатель
Немного истории
Профессиональная идентичность
Документация в IT
Писатель и компания
Документирование в Яндексе
Кто мы
О чем мы пишем
Как мы работаем
Разбираемся
Пишем
Оцениваем результат
12 / 41

16. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Процесс разработки...
и место документации в нем
13 / 41

17. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Документация в меняющемся мире
• Распределение ценности
на разных этапах:
• 1940—1980 hardware
• 1980—2000 software
• 2000—2014 service (user
attention)
• Рост объема написанного
кода с годами.
14 / 41

18. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Документация в меняющемся мире
• Распределение ценности
на разных этапах:
• 1940—1980 hardware
• 1980—2000 software
• 2000—2014 service (user
attention)
• Рост объема написанного
кода с годами.
14 / 41

19. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Документация в меняющемся мире
• Распределение ценности
на разных этапах:
• 1940—1980 hardware
• 1980—2000 software
• 2000—2014 service (user
attention)
• Рост объема написанного
кода с годами.
14 / 41

20. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Документация в меняющемся мире
• Распределение ценности
на разных этапах:
• 1940—1980 hardware
• 1980—2000 software
• 2000—2014 service (user
attention)
• Рост объема написанного
кода с годами.
Amit Deshpande, Dirk Riehle The Total
Growth of Open Source // Proceedings
of the Fourth Conference on Open
Source Systems (OSS 2008). Springer
Verlag, 2008. Page 197-209.
14 / 41

21. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Тем временем в России...
15 / 41

22. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
План
Профессия — технический писатель
Немного истории
Профессиональная идентичность
Документация в IT
Писатель и компания
Документирование в Яндексе
Кто мы
О чем мы пишем
Как мы работаем
Разбираемся
Пишем
Оцениваем результат
16 / 41

23. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Внутренняя документация
17 / 41

24. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Внутренняя документация
17 / 41

25. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Служба извлечения смысла
Иероним Босх, Извлечение
камня глупости (1494)
• Извлечение тайных знаний
• Ответы на незаданные
вопросы
• Отсеивание ненужного
• Исправление нелогичного
18 / 41

26. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Задачи техписателя
Разобраться −→ Изложить
19 / 41

27. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Задачи техписателя
Разобраться −→ Изложить
19 / 41

28. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
План
Профессия — технический писатель
Немного истории
Профессиональная идентичность
Документация в IT
Писатель и компания
Документирование в Яндексе
Кто мы
О чем мы пишем
Как мы работаем
Разбираемся
Пишем
Оцениваем результат
20 / 41

29. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Сколько нас
В идеале В Яндексе
21 / 41

30. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Команда
22 / 41

31. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Команда (в разрезе)
Возраст
23 / 41

32. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Команда (в разрезе)
Пол и образование
24 / 41

33. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Команда (в разрезе)
Образование
25 / 41

34. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
План
Профессия — технический писатель
Немного истории
Профессиональная идентичность
Документация в IT
Писатель и компания
Документирование в Яндексе
Кто мы
О чем мы пишем
Как мы работаем
Разбираемся
Пишем
Оцениваем результат
26 / 41

35. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Что мы документируем
• Внутренние технологии
• Внешние API
• Open Source технологии
Яндекса
• Сервисы Яндекса для
пользователей
Переводы
• на английский
DOC.yandex-team.ru
27 / 41

36. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Что мы документируем
• Внутренние технологии
• Внешние API
• Open Source технологии
Яндекса
• Сервисы Яндекса для
пользователей
Переводы
• на английский
API.yandex.ru | .com |
.com.tr
27 / 41

37. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Что мы документируем
• Внутренние технологии
• Внешние API
• Open Source технологии
Яндекса
• Сервисы Яндекса для
пользователей
Переводы
• на английский
BEM.info | github
27 / 41

38. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Что мы документируем
• Внутренние технологии
• Внешние API
• Open Source технологии
Яндекса
• Сервисы Яндекса для
пользователей
Переводы
• на английский
HELP.yandex.ru | .ua |
.com | .com.tr
27 / 41

39. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
План
Профессия — технический писатель
Немного истории
Профессиональная идентичность
Документация в IT
Писатель и компания
Документирование в Яндексе
Кто мы
О чем мы пишем
Как мы работаем
Разбираемся
Пишем
Оцениваем результат
28 / 41

40. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
План
Профессия — технический писатель
Немного истории
Профессиональная идентичность
Документация в IT
Писатель и компания
Документирование в Яндексе
Кто мы
О чем мы пишем
Как мы работаем
Разбираемся
Пишем
Оцениваем результат
29 / 41

41. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Глубокое погружение в предмет
Из всех источников:
• работа с продуктом
• разговоры разработчиков
• вики
• багтрекер
• рассылки
• КОД
30 / 41

42. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Глубокое погружение в предмет
Во всех ролях:
• менеджер
• разработчик
• тестировщик
• пользователь
• поддержка
30 / 41

43. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
План
Профессия — технический писатель
Немного истории
Профессиональная идентичность
Документация в IT
Писатель и компания
Документирование в Яндексе
Кто мы
О чем мы пишем
Как мы работаем
Разбираемся
Пишем
Оцениваем результат
31 / 41

44. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Используем профессиональные инструменты
• Большие объемы
• Требуется постоянное обновление
• Много перекрестных ссылок
• Много заимствований (цитирования)
• Различные выходные форматы: HTML и PDF
• DITA XML + SernaFree
32 / 41

45. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Используем профессиональные инструменты
• Большие объемы
• Требуется постоянное обновление
• Много перекрестных ссылок
• Много заимствований (цитирования)
• Различные выходные форматы: HTML и PDF
• DITA XML + SernaFree
32 / 41

46. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Эффект «многабукаф»
33 / 41

47. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Коротко и ясно
Общие требования к изложению
• Предложения должны быть короткими: одно предложение
– один факт. Нормальная длина: 7–15 слов.
• Абзацы должны быть не длинными: один абзац – одна
законченная мысль. Нормальная длина: 3–5 предложений.
• Подзаголовки нужны. Выделяйте в тексте логические блоки
и озаглавливайте их. Помните, что в сплошном тексте
трудно ориентироваться.
• Заголовки делайте максимально короткими и
однозначными по смыслу (в конце заголовка знаки
препинания не ставятся никогда).
34 / 41

48. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Перекрестная вычитка
35 / 41

49. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
План
Профессия — технический писатель
Немного истории
Профессиональная идентичность
Документация в IT
Писатель и компания
Документирование в Яндексе
Кто мы
О чем мы пишем
Как мы работаем
Разбираемся
Пишем
Оцениваем результат
36 / 41

50. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Оценка качества
• отзывы
• посещаемость
• карты кликов (click maps)
http://metrika.yandex.ru
37 / 41

51. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Нас читают :)
38 / 41

52. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Следите за вакансиями
http://company.yandex.ru/job/vacancies/
39 / 41

53. .....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
....
.
....
.
.....
.
....
.
.....
.
....
.
....
.
Спасибо за внимание!
Контакты
• Кирилл Маслинский maslinsky@yandex-team.ru
• Вакансии разработчиков технической документации на
company.yandex.ru
40 / 41

54. .
Я.Технический писатель
Кирилл Маслинский
maslinsky@yandex-team.ru
ведущий разработчик технической документации
Яндекс, Санкт-Петербург
18.03.2014 / Я.Студент Москва
........ ............................................................ .... ..... ........ .