Технический писатель в 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
   РЕАЛЬНОСТЬ
   

   View Slide

2. ЦЕЛИ
   1. Познакомить с профессией технического писателя
   2. Поделиться опытом разработки документации в IT компании
   3. Рассказать про жанры документации, в которых мы пишем
   4. Сравнить собственные ожидания от профессии и действительность
   

   View Slide

3. О КОМПАНИИ
   

   View Slide

4. UNIGINE. ПРОДУКТЫ
   • 3D платформа UNIGINE
    исходный код платформы
    визуальный редактор
    SDK-браузер
    консольные инструменты
    документация
   • Продукты на базе движка
    бенчмарки
    симуляторы
    игры
   • Web-ресурсы
    промо-сайт
    портал для разработчиков
   

   View Slide

5. View Slide

6. View Slide

7. View Slide

8. View Slide

9. View Slide

10. View Slide

11. View Slide

12. КТО ТАКОЙ
    ТЕХНИЧЕСКИЙ ПИСАТЕЛЬ?
    

    View Slide

13. ПЕРЕВОДЧИК vs ТЕХНИЧЕСКИЙ ПИСАТЕЛЬ
    

    View Slide

14. ТЕХНИЧЕСКИЙ ПИСАТЕЛЬ
    ОТЧАСТИ:
    • Писатель
    • Журналист
    • Разработчик
    • Тестировщик
    • Иллюстратор
    

    View Slide

15. ОБЪЕМЫ РАБОТЫ
    

    View Slide

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 тех. писателя
    ПРОДУКТ ДОКУМЕНТАЦИЯ
    

    View Slide

17. ПРОЦЕСС НАПИСАНИЯ
    СТАТЬИ
    

    View Slide

18. • Определение ЦА
    • Опрос программистов, чтение кода
    • Отсеивание ненужного
    • Тестирование
    • Разработка (опционально)
    • Написание документации
    • Вычитка
    

    View Slide

19. РАСПРЕДЕЛЕНИЕ ВРЕМЕНИ
    

    View Slide

20. АУДИТОРИЯ
    

    View Slide

21. • Программисты (графики,
    логики, инструментария)
    и технические художники
    • 3D-художники
    • Потенциальные покупатели
     Менеджеры
     Программисты
     3D-художники
    • Все у кого есть интерес к
    технологии
    ВНУТРЕННЯЯ ВНЕШНЯЯ
    

    View Slide

22. ЖАНРЫ ДОКУМЕНТАЦИИ
    

    View Slide

23. 1. МЕНТАЛЬНАЯ МОДЕЛЬ
    • Базовые сущности и их взаимосвязи
    • Принципы работы подсистем
    • Связи со смежными областями
    ! Повествование в стиле Википедии
    

    View Slide

24. 2. РУКОВОДСТВО ПОЛЬЗОВАТЕЛЯ
    (GUI)
    • Описание интерфейса инструментов
    • Требуемое рабочее окружение
    • Краевые значения параметров
    • Влияние одних параметров на другие
    ! Текст, изображения (+GIF)
    

    View Slide

25. 3. СПРАВОЧНИК API
    • Описание классов, функций
    и аргументов
    • Ограничения и краевые случаи
    • Примеры использования кода
    ! Быстрый поиск
    

    View Slide

26. 4. ТУТОРИАЛ
    • Пошаговое руководство с «нуля»
    до результата
    • Объясняем, как сделать, а не почему
    так устроено
    ! Много картинок, видео
    

    View Slide

27. СТАНДАРТЫ,
    ИНСТРУМЕНТЫ,
    КАЧЕСТВО
    

    View Slide

28. СТАНДАРТЫ
    • Пишем в свободном стиле, не по ГОСТу
    • Пишем себе сами стандарты
    • Используем Microsoft Manual of Style
    • Обучались онлайн в Sprott business school
    

    View Slide

29. View Slide

30. View Slide

31. ИНСТРУМЕНТЫ
    • Автогенерация API
    • Система контроля версий
    • Тесты, валидация
    • Входные: XML, CMS
    • Выходные: HTML
    

    View Slide

32. КАЧЕСТВО
    • Отзывы клиентов
    • Частота появления запросов на форуме
    • Тест на новичках в компании
    • Product-менеджеры
    

    View Slide

33. ДЕМОГРАФИЯ
    

    View Slide

34. Высшее образование
    Пол
    Дополнительное образование
    Возраст
    

    View Slide

35. ОЖИДАНИЯ
    vs
    РЕАЛЬНОСТЬ
    

    View Slide

36. Будет время
    досконально
    изучить продукт
    Первая задача
    «Применение
    процедурных генераторов
    в создании контента для
    real-time 3D приложений»
    

    View Slide

37. Программисты будут
    подробно рассказывать
    про сделанную работу,
    и как этим
    пользоваться
    Сделал, но молчит
    как партизан
    

    View Slide

38. View Slide

39. View Slide

40. Буду работать над
    одной статьей, доведу
    ее до совершенства
    Работаю над десятью
    параллельно, уже
    не помню о чем была
    первая
    

    View Slide

41. Напишу один раз хорошо
    и всем будет счастье
    Полностью
    переписываю
    одну и ту же статью
    раз в два месяца
    

    View Slide

42. View Slide

43. ВЫВОДЫ
    

    View Slide

44. НЕОБХОДИМЫЕ
    ЛИЧНЫЕ КАЧЕСТВА
    • Нужно быстро осваивать
    большие объемы информации
    • Любовь к людям
    • Многозадачность
    • Оптимизм
    • Причастность к крутой
    технологии и общество умных
    коллег
    • Широкий IT кругозор
    • Навык описания сложных вещей
    простыми словами
    • Регулярная практика английского
    в различных жанрах
    • Возможность развиваться в
    любом направлении
    параллельно
    ПЛЮСЫ
    

    View Slide

45. СПАСИБО!
    Ольга Кириченко
    qubblr@unigine.com
    unigine.com
    

    View Slide