Технический писатель в IT: ожидание/реальность (Ольга Кириченко)

http://docfactor.ru.

4 ноября 2016, Новосибирск

Технический писатель в IT: ожидание/реальность (Ольга Кириченко, UNIGINE, Томск)

Видеозапись: https://www.youtube.com/watch?v=fFQOvwTE_vM

«Суровые сибирские техписатели читают и пишут код на С++!», и другие реальные истории из жизни штатного сотрудника томской компании UNIGINE, разрабатывающей собственную платформу 3D-графики.

В своем докладе я расскажу про:

- Роль отдела технической документации для продукта;
- Процессы и инструменты разработки документации в нашей компании;
- Оценку качества разработанной документации;
- Плюсы и минусы профессии;
- Пути развития и карьерный рост специалистов;
- Личные качества и знания, необходимые для достижения успеха в нашей отрасли.

DocFactor — конференция о технической документации и ее роли в разработке ПО.

Подробнее: http://docfactor.ru

Transcript

1. ТЕХНИЧЕСКИЙ ПИСАТЕЛЬ: Ольга Кириченко, ведущий технический писатель UNIGINE, Томск ОЖИДАНИЕ VS РЕАЛЬНОСТЬ
2. ЦЕЛИ 1. Познакомить с профессией технического писателя 2. Поделиться опытом разработки документации в IT компании 3. Рассказать про жанры документации, в которых мы пишем 4. Сравнить собственные ожидания от профессии и действительность
3. О КОМПАНИИ
4. UNIGINE. ПРОДУКТЫ • 3D платформа UNIGINE  исходный код платформы  визуальный редактор  SDK-браузер  консольные инструменты  документация • Продукты на базе движка  бенчмарки  симуляторы  игры • Web-ресурсы  промо-сайт  портал для разработчиков
12. КТО ТАКОЙ ТЕХНИЧЕСКИЙ ПИСАТЕЛЬ?
13. ПЕРЕВОДЧИК vs ТЕХНИЧЕСКИЙ ПИСАТЕЛЬ
14. ТЕХНИЧЕСКИЙ ПИСАТЕЛЬ ОТЧАСТИ: • Писатель • Журналист • Разработчик • Тестировщик • Иллюстратор
15. ОБЪЕМЫ РАБОТЫ
16. • 13 программистов • Более 12 лет R&D • Более 1 000 000 строк кода на С++ • 5-6 релизов SDK в год • Объем изменений в неделю: ~10 новых методов API, ~2-3 фичи в движке и редакторе • 1400 статей в одной версии (700 000 слов) • 3000 иллюстраций • Отдельная версия документации для каждого релиза • 3 языка (En, Ru, Ch) • Более 5000 методов API x3 языка (С++, C#, UnigineScript) • 3 тех. писателя ПРОДУКТ ДОКУМЕНТАЦИЯ
17. ПРОЦЕСС НАПИСАНИЯ СТАТЬИ
18. • Определение ЦА • Опрос программистов, чтение кода • Отсеивание ненужного • Тестирование • Разработка (опционально) • Написание документации • Вычитка
19. РАСПРЕДЕЛЕНИЕ ВРЕМЕНИ
20. АУДИТОРИЯ
21. • Программисты (графики, логики, инструментария) и технические художники • 3D-художники • Потенциальные покупатели  Менеджеры  Программисты  3D-художники • Все у кого есть интерес к технологии ВНУТРЕННЯЯ ВНЕШНЯЯ
22. ЖАНРЫ ДОКУМЕНТАЦИИ
23. 1. МЕНТАЛЬНАЯ МОДЕЛЬ • Базовые сущности и их взаимосвязи • Принципы работы подсистем • Связи со смежными областями ! Повествование в стиле Википедии
24. 2. РУКОВОДСТВО ПОЛЬЗОВАТЕЛЯ (GUI) • Описание интерфейса инструментов • Требуемое рабочее окружение • Краевые значения параметров • Влияние одних параметров на другие ! Текст, изображения (+GIF)
25. 3. СПРАВОЧНИК API • Описание классов, функций и аргументов • Ограничения и краевые случаи • Примеры использования кода ! Быстрый поиск
26. 4. ТУТОРИАЛ • Пошаговое руководство с «нуля» до результата • Объясняем, как сделать, а не почему так устроено ! Много картинок, видео
27. СТАНДАРТЫ, ИНСТРУМЕНТЫ, КАЧЕСТВО
28. СТАНДАРТЫ • Пишем в свободном стиле, не по ГОСТу • Пишем себе сами стандарты • Используем Microsoft Manual of Style • Обучались онлайн в Sprott business school
31. ИНСТРУМЕНТЫ • Автогенерация API • Система контроля версий • Тесты, валидация • Входные: XML, CMS • Выходные: HTML
32. КАЧЕСТВО • Отзывы клиентов • Частота появления запросов на форуме • Тест на новичках в компании • Product-менеджеры
33. ДЕМОГРАФИЯ
34. Высшее образование Пол Дополнительное образование Возраст
35. ОЖИДАНИЯ vs РЕАЛЬНОСТЬ
36. Будет время досконально изучить продукт Первая задача «Применение процедурных генераторов в создании контента для real-time 3D приложений»
37. Программисты будут подробно рассказывать про сделанную работу, и как этим пользоваться Сделал, но молчит как партизан
40. Буду работать над одной статьей, доведу ее до совершенства Работаю над десятью параллельно, уже не помню о чем была первая
41. Напишу один раз хорошо и всем будет счастье Полностью переписываю одну и ту же статью раз в два месяца
43. ВЫВОДЫ
44. НЕОБХОДИМЫЕ ЛИЧНЫЕ КАЧЕСТВА • Нужно быстро осваивать большие объемы информации • Любовь к людям • Многозадачность • Оптимизм • Причастность к крутой технологии и общество умных коллег • Широкий IT кругозор • Навык описания сложных вещей простыми словами • Регулярная практика английского в различных жанрах • Возможность развиваться в любом направлении параллельно ПЛЮСЫ
45. СПАСИБО! Ольга Кириченко qubblr@unigine.com unigine.com