Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

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

http://docfactor.ru.

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

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

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

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

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

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

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

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

More Decks by DocFactor: конференция о технической документации

Other Decks in Education

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. СПАСИБО!
    Ольга Кириченко
    [email protected]
    unigine.com

    View Slide