[SnowOne 2023] Семён Факторович: Нужно ли писать документацию?

Все мы любим хорошо задокументированные API и понятную документацию к языкам, библиотекам и фреймворкам.

Но вот писать документацию никто не любит.

Мы поговорим вот о чем:
1) Зачем нужна документация и что будет, если ее не будет.
2) Как рождается хорошая документация и почему ее сложно писать.
3) Должен ли разработчик писать документацию и если да, то как этому научиться.
4) Откуда взялась профессия технического писателя и стоит ли о ней задумываться выпускнику IT-специальности.

Transcript

1. Нужно ли писать документацию?
   Семëн Факторович, documentat.io
   factorized
   

   View Slide

2. • Семён Факторóвич (Новосибирск)
   • Выпускник ФФ НГУ и ФИТ НГУ
   • Разработчик → технический писатель
   • Занимаюсь технической документацией с 2012 года
   • С 2018 руковожу компанией документационного
   консалтинга
   Кто здесь?
   

   View Slide

3. • Семён Факторóвич (Новосибирск)
   • Выпускник ФФ НГУ и ФИТ НГУ
   • Разработчик → технический писатель
   • Занимаюсь технической документацией с 2012 года
   • С 2018 руковожу компанией документационного
   консалтинга Documentat
   Кто здесь?
   

   View Slide

4. Пишем документацию на заказ,
   внедряем своих техписателей в чужие команды
   Учим техписателей и разработчиков писать документацию
   documentat.io
   

   View Slide

5. Кто из вас хоть раз писал документацию?
   

   View Slide

6. Кто из вас хоть раз писал документацию?
   

   View Slide

7. Кто из вас хоть раз писал документацию?
   (комменты в коде и Javadoc не считаются)
   

   View Slide

8. Кто из вас хоть раз писал документацию?
   (комменты в коде и Javadoc не считаются)
   

   View Slide

9. Какая бывает документация?
   

   View Slide

10. View Slide

11. View Slide

12. View Slide

13. View Slide

14. View Slide

15. View Slide

16. View Slide

17. View Slide

18. Документация: основные черты
    

    View Slide

19. 1. Рассказывает, как пользоваться программной
    системой или как она устроена.
    API, сигнатуры методов в библиотеке, перечень ключей CLI…
    Документация: основные черты
    

    View Slide

20. 2. Не продает, не рекламирует, не убеждает купить.
    Нейтрально излагает факты о системе или учит ей пользоваться.
    Документация: основные черты
    

    View Slide

21. 3. Разрабатывается той же командой, что создает
    программную систему.
    Ответ на StackOverflow или статья на Хабре — не документация.
    Документация: основные черты
    

    View Slide

22. 4. Самостоятельный проектный артефакт.
    Живет и поставляется отдельно, всегда отделена от кода.
    Документация: основные черты
    

    View Slide

23. Неожиданные выводы
    

    View Slide

24. 1. Javadoc — документация, но только когда он собран
    в HTML и доступен отдельно от кода.
    И это вовсе не единственный и не самый популярный вид документации.
    Неожиданные выводы
    

    View Slide

25. 2. Комментарии в коде — вообще не документация.
    А часть кода.
    Неожиданные выводы
    

    View Slide

26. Комментарии как часть культуры кодирования
    

    View Slide

27. Комментарии как часть культуры кодирования
    …
    Внятное именование переменных
    Следование стайлгайду
    Разумная обработка ошибок
    Понятные комментарии
    Использовать исключения так, как завещал Кучук
    …
    

    View Slide

28. Какая еще бывает документация?
    

    View Slide

29. • Внутренние API
    Какая еще бывает документация?
    

    View Slide

30. • Внутренние API
    Какая еще бывает документация?
    

    View Slide

31. • Внутренние API
    Какая еще бывает документация?
    

    View Slide

32. • Архитектура системы
    Какая еще бывает документация?
    

    View Slide

33. • Архитектура системы
    Какая еще бывает документация?
    

    View Slide

34. Архитектурная документация
    

    View Slide

35. • Основные принципы устройства и дизайна кода
    Архитектурная документация
    

    View Slide

36. • Основные принципы устройства и дизайна кода
    • Разбивка по компонентам, процессам, потокам исполнения…
    Архитектурная документация
    

    View Slide

37. • Основные принципы устройства и дизайна кода
    • Разбивка по компонентам, процессам, потокам исполнения…
    • Используемые алгоритмы
    Архитектурная документация
    

    View Slide

38. • Основные принципы устройства и дизайна кода
    • Разбивка по компонентам, процессам, потокам исполнения…
    • Используемые алгоритмы
    • Data flows
    Архитектурная документация
    

    View Slide

39. • Основные принципы устройства и дизайна кода
    • Разбивка по компонентам, процессам, потокам исполнения…
    • Используемые алгоритмы
    • Data flows
    Архитектурная документация
    

    View Slide

40. • Основные принципы устройства и дизайна кода
    • Разбивка по компонентам, процессам, потокам исполнения…
    • Используемые алгоритмы
    • Data flows
    Никогда не автогенерится, всегда пишется вручную
    Архитектурная документация
    

    View Slide

41. Chromium multi-process architecture
    

    View Slide

42. AOSABook
    

    View Slide

43. Код — лучшая документация?
    

    View Slide

44. • Да, но архитектурная документация читается быстрее
    Код — лучшая документация?
    

    View Slide

45. • Да, но архитектурная документация читается быстрее
    • А еще код может не быть источником истины (баги!)
    Код — лучшая документация?
    

    View Slide

46. • Да, но архитектурная документация читается быстрее
    • А еще код может не быть источником истины (баги!)
    • А еще архитектурный документ может содержать инфу,
    которой нет в коде
    Код — лучшая документация?
    

    View Slide

47. • Да, но архитектурная документация читается быстрее
    • А еще код может не быть источником истины (баги!)
    • А еще архитектурный документ может содержать инфу,
    которой нет в коде
    • Почему использован дизайн-паттерн А, а не Б
    Код — лучшая документация?
    

    View Slide

48. • Да, но архитектурная документация читается быстрее
    • А еще код может не быть источником истины (баги!)
    • А еще архитектурный документ может содержать инфу,
    которой нет в коде
    • Почему использован дизайн-паттерн А, а не Б
    • Как всё было реализовано раньше и почему мы решили провести рефакторинг
    Код — лучшая документация?
    

    View Slide

49. • Да, но архитектурная документация читается быстрее
    • А еще код может не быть источником истины (баги!)
    • А еще архитектурный документ может содержать инфу,
    которой нет в коде
    • Почему использован дизайн-паттерн А, а не Б
    • Как всё было реализовано раньше и почему мы решили провести рефакторинг
    • Почему выбран именно этот язык программирования или технологический стек
    Код — лучшая документация?
    

    View Slide

50. Документация как «анти-юзкейс»
    

    View Slide

51. Документация как «анти-юзкейс»
    Не написал в техподдержку…
    

    View Slide

52. Документация как «анти-юзкейс»
    … а прочитал документацию
    Не написал в техподдержку…
    

    View Slide

53. Документация как «анти-юзкейс»
    Не постучался в Телеграм к коллеге…
    

    View Slide

54. Документация как «анти-юзкейс»
    … а прочитал документацию
    Не постучался в Телеграм к коллеге…
    

    View Slide

55. Документация как «анти-юзкейс»
    Не потратил неделю на чтение кода…
    

    View Slide

56. Документация как «анти-юзкейс»
    … а прочитал архитектурную документацию
    Не потратил неделю на чтение кода…
    

    View Slide

57. Документация облегчает коммуникацию
    

    View Slide

58. Архитектурная документация появляется тогда,
    когда тимлиду надоедает объяснять одно и то же
    по три раза в месяц
    

    View Slide

59. Пользовательская
    документация
    снижает нагрузку на
    техподдержку
    

    View Slide

60. Документация сохраняет информацию
    

    View Slide

61. Документация — это надежно.
    Документация сохраняет информацию
    

    View Slide

62. Документация — это надежно.
    А голова инженера — нет.
    Документация сохраняет информацию
    

    View Slide

63. Bus factor
    

    View Slide

64. Bus factor
    

    View Slide

65. Bus factor
    • Сколько инженеров должны попасть под автобус,
    чтобы работа команды полностью остановилась?
    • 1 — плохо
    • N (где N равен размеру команды) — хорошо
    

    View Slide

66. Равномерное распределение информации по команде
    

    View Slide

67. Равномерное распределение информации по команде
    

    View Slide

68. Равномерное распределение информации по команде
    

    View Slide

69. Равномерное распределение информации по команде
    

    View Slide

70. View Slide

71. View Slide

72. View Slide

73. View Slide

74. View Slide

75. View Slide

76. View Slide

77. View Slide

78. View Slide

79. View Slide

80. View Slide

81. ДОКУМЕНТАЦИЕЙ
    ДОКУМЕНТАЦЕИ
    

    View Slide

82. Что на самом деле происходит в индустрии
    

    View Slide

83. Что на самом деле происходит в индустрии
    

    View Slide

84. Что на самом деле происходит в индустрии
    

    View Slide

85. • «Документация покрывает от силы 40% кодовой
    базы»
    Что на самом деле происходит в индустрии
    

    View Slide

86. • «Документация покрывает от силы 40% кодовой
    базы»
    • «У нас вообще нет документации, хотя все понимают,
    что она нужна»
    Что на самом деле происходит в индустрии
    

    View Slide

87. • «Документация покрывает от силы 40% кодовой
    базы»
    • «У нас вообще нет документации, хотя все понимают,
    что она нужна»
    • «Документация есть, но в
    последний раз она обновлялась при
    Медведеве»
    Что на самом деле происходит в индустрии
    

    View Slide

88. Почему документации нет?
    

    View Slide

89. Почему документации нет?
    

    View Slide

90. Почему документации нет?
    

    View Slide

91. 1. Всегда некогда.
    Почему документации нет?
    

    View Slide

92. 1. Всегда некогда.
    2. Непрофильная активность для
    инженеров.
    Почему документации нет?
    

    View Slide

93. 1. Всегда некогда.
    2. Непрофильная активность для
    инженеров.
    3. Писать слова и фразы вообще
    сложно. Сложнее, чем код.
    Почему документации нет?
    

    View Slide

94. 1. Всегда некогда.
    2. Непрофильная активность для
    инженеров.
    3. Писать слова и фразы вообще
    сложно. Сложнее, чем код.
    4. Понятно описывать сложные
    вещи — огромный труд (сходство с
    преподаванием).
    Почему документации нет?
    

    View Slide

95. 1. Всегда некогда.
    2. Непрофильная активность для
    инженеров.
    3. Писать слова и фразы вообще
    сложно. Сложнее, чем код.
    4. Понятно описывать сложные
    вещи — огромный труд (сходство с
    преподаванием).
    5. Для кода есть паттерны и best
    practices. Для документации их нет.
    Почему документации нет?
    

    View Slide

96. Что же делать?
    

    View Slide

97. • Инженерам нужно перестать писать документацию
    Что же делать?
    

    View Slide

98. • Инженерам нужно перестать писать документацию
    • И нанять для этого специального человека
    Что же делать?
    

    View Slide

99. Технический писатель
    

    View Slide

100. Технический писатель
     

     View Slide

101. Специалист, умеющий:
     • целеполагать
     • проектировать
     • и писать
     документацию.
     Технический писатель
     

     View Slide

102. Специалист, умеющий:
     • целеполагать
     • проектировать
     • и писать
     документацию.
     Технический писатель
     

     View Slide

103. Специалист, умеющий:
     • целеполагать
     • проектировать
     • и писать
     документацию.
     Технический писатель
     

     View Slide

104. Технический писатель
     

     View Slide

105. • Любит писать, получает от этого удовольствие
     Технический писатель
     

     View Slide

106. • Любит писать, получает от этого удовольствие
     • Любит объяснять и доносить информацию
     Технический писатель
     

     View Slide

107. • Любит писать, получает от этого удовольствие
     • Любит объяснять и доносить информацию
     • Пишет емко и понятно
     Технический писатель
     

     View Slide

108. Технический писатель: как получает инфу?
     

     View Slide

109. • Общение с инженерами
     Технический писатель: как получает инфу?
     

     View Slide

110. • Общение с инженерами
     • Самостоятельное изучение продукта (подергать API,
     попользоваться библиотекой)
     Технический писатель: как получает инфу?
     

     View Slide

111. • Общение с инженерами
     • Самостоятельное изучение продукта (подергать API,
     попользоваться библиотекой)
     • Чтение кода
     Технический писатель: как получает инфу?
     

     View Slide

112. Технический писатель
     

     View Slide

113. Технический писатель
     

     View Slide

114. Технический писатель
     • Технический бэкграунд
     

     View Slide

115. Технический писатель
     • Технический бэкграунд
     Computer science, программная
     инженерия, опыт
     программирования…
     

     View Slide

116. Технический писатель
     • Технический бэкграунд
     Computer science, программная
     инженерия, опыт
     программирования…
     • Гуманитарная жилка
     

     View Slide

117. Технический писатель
     • Технический бэкграунд
     Computer science, программная
     инженерия, опыт
     программирования…
     • Гуманитарная жилка
     Хороший письменный стиль,
     умение объяснять…
     

     View Slide

118. Технический писатель
     

     View Slide

119. • Два высших образования?
     Технический писатель
     

     View Slide

120. • Два высших образования?
     • На самом деле хотя бы одно
     Технический писатель
     

     View Slide

121. • Два высших образования?
     • На самом деле хотя бы одно
     • Гуманитарий, который самостоятельно добрал айтишной
     фундаментальщины
     Технический писатель
     

     View Slide

122. • Два высших образования?
     • На самом деле хотя бы одно
     • Гуманитарий, который самостоятельно добрал айтишной
     фундаментальщины
     • Технарь, который [почему-то] любит и хочет писать буквы и слова
     Технический писатель
     

     View Slide

123. Технический писатель как карьерная опция
     

     View Slide

124. • Молодая, набирающая популярность IT-профессия
     Технический писатель как карьерная опция
     

     View Slide

125. • Молодая, набирающая популярность IT-профессия
     • Компании стремительно осознают важность
     документации
     Технический писатель как карьерная опция
     

     View Slide

126. • Молодая, набирающая популярность IT-профессия
     • Компании стремительно осознают важность
     документации
     • Техписателя с айтишным образованием готовы
     оторвать с руками
     Технический писатель как карьерная опция
     

     View Slide

127. Технический писатель: где поучиться?
     

     View Slide

128. • Университетских специальностей [почти] нет
     Технический писатель: где поучиться?
     

     View Slide

129. • Университетских специальностей [почти] нет
     • Онлайн-курсы
     Технический писатель: где поучиться?
     

     View Slide

130. • Университетских специальностей [почти] нет
     • Онлайн-курсы
     • documentat.io/courses
     Технический писатель: где поучиться?
     

     View Slide

131. • Университетских специальностей [почти] нет
     • Онлайн-курсы
     • documentat.io/courses
     • IT-образование и умение внятно писать = позиция
     мидл-техписателя в большинстве российских
     компаний
     Технический писатель: где поучиться?
     

     View Slide

132. Не хочу в техписатели, хочу писать код
     

     View Slide

133. • Скорее всего, вам придется писать документацию
     Не хочу в техписатели, хочу писать код
     

     View Slide

134. • Скорее всего, вам придется писать документацию
     • Стоит немного поучиться паттернам
     документирования
     Не хочу в техписатели, хочу писать код
     

     View Slide

135. • Скорее всего, вам придется писать документацию
     • Стоит немного поучиться паттернам
     документирования
     • и вообще научиться эффективно складывать слова в предложения
     Не хочу в техписатели, хочу писать код
     

     View Slide

136. Что почитать разработчику о документации
     

     View Slide

137. «Взгляд на документацию с точки зрения бизнеса»
     Что почитать разработчику о документации
     

     View Slide

138. «Взгляд на документацию с точки зрения бизнеса»
     What nobody tells you about documentation
     Что почитать разработчику о документации
     

     View Slide

139. «Взгляд на документацию с точки зрения бизнеса»
     What nobody tells you about documentation
     c4model.com и arc42.org, методологии
     документирования архитектуры
     Что почитать разработчику о документации
     

     View Slide

140. View Slide

141. Заменит ли ChatGPT техписателей?
     

     View Slide

142. Заменит ли ChatGPT техписателей?
     

     View Slide

143. Заменит ли ChatGPT техписателей?
     

     View Slide

144. Заменит ли ChatGPT техписателей?
     • Документация опирается на закрытое знание о
     проприетарной системе
     

     View Slide

145. Заменит ли ChatGPT техписателей?
     • Документация опирается на закрытое знание о
     проприетарной системе
     • Вы пускаете чужой AI в вашу кодовую базу?
     

     View Slide

146. Заменит ли ChatGPT техписателей?
     • Документация опирается на закрытое знание о
     проприетарной системе
     • Вы пускаете чужой AI в вашу кодовую базу?
     • Если да, то, скорее всего, он уже пишет код за вас
     

     View Slide

147. Заменит ли ChatGPT техписателей?
     Да.
     Примерно тогда же, когда и программистов.
     

     View Slide

148. View Slide

149. • Документация сохраняет знания о системе и
     удешевляет обмен ими
     • Техписатель — специалист, снимающий
     документационную нагрузку с инженеров
     • Любите писать? Приходите в эту профессию
     • Поучитесь у экспертов: documentat.io/courses
     Подытожим
     

     View Slide

150. Нужно ли
     писать
     документацию?
     Семëн Факторович, documentat.io
     factorized
     

     View Slide