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

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

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

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

Transcript

1. Нужно ли писать документацию? Семëн Факторович, documentat.io factorized
2. • Семён Факторóвич (Новосибирск) • Выпускник ФФ НГУ и ФИТ НГУ • Разработчик → технический писатель • Занимаюсь технической документацией с 2012 года • С 2018 руковожу компанией документационного консалтинга Кто здесь?
3. • Семён Факторóвич (Новосибирск) • Выпускник ФФ НГУ и ФИТ НГУ • Разработчик → технический писатель • Занимаюсь технической документацией с 2012 года • С 2018 руковожу компанией документационного консалтинга Documentat Кто здесь?
4. Пишем документацию на заказ, внедряем своих техписателей в чужие команды Учим техписателей и разработчиков писать документацию documentat.io
5. Кто из вас хоть раз писал документацию?
6. Кто из вас хоть раз писал документацию?
7. Кто из вас хоть раз писал документацию? (комменты в коде и Javadoc не считаются)
8. Кто из вас хоть раз писал документацию? (комменты в коде и Javadoc не считаются)
9. Какая бывает документация?
18. Документация: основные черты
19. 1. Рассказывает, как пользоваться программной системой или как она устроена. API, сигнатуры методов в библиотеке, перечень ключей CLI… Документация: основные черты
20. 2. Не продает, не рекламирует, не убеждает купить. Нейтрально излагает факты о системе или учит ей пользоваться. Документация: основные черты
21. 3. Разрабатывается той же командой, что создает программную систему. Ответ на StackOverflow или статья на Хабре — не документация. Документация: основные черты
22. 4. Самостоятельный проектный артефакт. Живет и поставляется отдельно, всегда отделена от кода. Документация: основные черты
23. Неожиданные выводы
24. 1. Javadoc — документация, но только когда он собран в HTML и доступен отдельно от кода. И это вовсе не единственный и не самый популярный вид документации. Неожиданные выводы
25. 2. Комментарии в коде — вообще не документация. А часть кода. Неожиданные выводы
26. Комментарии как часть культуры кодирования
27. Комментарии как часть культуры кодирования … Внятное именование переменных Следование стайлгайду Разумная обработка ошибок Понятные комментарии Использовать исключения так, как завещал Кучук …
28. Какая еще бывает документация?
29. • Внутренние API Какая еще бывает документация?
30. • Внутренние API Какая еще бывает документация?
31. • Внутренние API Какая еще бывает документация?
32. • Архитектура системы Какая еще бывает документация?
33. • Архитектура системы Какая еще бывает документация?
34. Архитектурная документация
35. • Основные принципы устройства и дизайна кода Архитектурная документация
36. • Основные принципы устройства и дизайна кода • Разбивка по компонентам, процессам, потокам исполнения… Архитектурная документация
37. • Основные принципы устройства и дизайна кода • Разбивка по компонентам, процессам, потокам исполнения… • Используемые алгоритмы Архитектурная документация
38. • Основные принципы устройства и дизайна кода • Разбивка по компонентам, процессам, потокам исполнения… • Используемые алгоритмы • Data flows Архитектурная документация
39. • Основные принципы устройства и дизайна кода • Разбивка по компонентам, процессам, потокам исполнения… • Используемые алгоритмы • Data flows Архитектурная документация
40. • Основные принципы устройства и дизайна кода • Разбивка по компонентам, процессам, потокам исполнения… • Используемые алгоритмы • Data flows Никогда не автогенерится, всегда пишется вручную Архитектурная документация
41. Chromium multi-process architecture
42. AOSABook
43. Код — лучшая документация?
44. • Да, но архитектурная документация читается быстрее Код — лучшая документация?
45. • Да, но архитектурная документация читается быстрее • А еще код может не быть источником истины (баги!) Код — лучшая документация?
46. • Да, но архитектурная документация читается быстрее • А еще код может не быть источником истины (баги!) • А еще архитектурный документ может содержать инфу, которой нет в коде Код — лучшая документация?
47. • Да, но архитектурная документация читается быстрее • А еще код может не быть источником истины (баги!) • А еще архитектурный документ может содержать инфу, которой нет в коде • Почему использован дизайн-паттерн А, а не Б Код — лучшая документация?
48. • Да, но архитектурная документация читается быстрее • А еще код может не быть источником истины (баги!) • А еще архитектурный документ может содержать инфу, которой нет в коде • Почему использован дизайн-паттерн А, а не Б • Как всё было реализовано раньше и почему мы решили провести рефакторинг Код — лучшая документация?
49. • Да, но архитектурная документация читается быстрее • А еще код может не быть источником истины (баги!) • А еще архитектурный документ может содержать инфу, которой нет в коде • Почему использован дизайн-паттерн А, а не Б • Как всё было реализовано раньше и почему мы решили провести рефакторинг • Почему выбран именно этот язык программирования или технологический стек Код — лучшая документация?
50. Документация как «анти-юзкейс»
51. Документация как «анти-юзкейс» Не написал в техподдержку…
52. Документация как «анти-юзкейс» … а прочитал документацию Не написал в техподдержку…
53. Документация как «анти-юзкейс» Не постучался в Телеграм к коллеге…
54. Документация как «анти-юзкейс» … а прочитал документацию Не постучался в Телеграм к коллеге…
55. Документация как «анти-юзкейс» Не потратил неделю на чтение кода…
56. Документация как «анти-юзкейс» … а прочитал архитектурную документацию Не потратил неделю на чтение кода…
57. Документация облегчает коммуникацию
58. Архитектурная документация появляется тогда, когда тимлиду надоедает объяснять одно и то же по три раза в месяц
59. Пользовательская документация снижает нагрузку на техподдержку
60. Документация сохраняет информацию
61. Документация — это надежно. Документация сохраняет информацию
62. Документация — это надежно. А голова инженера — нет. Документация сохраняет информацию
63. Bus factor
64. Bus factor
65. Bus factor • Сколько инженеров должны попасть под автобус, чтобы работа команды полностью остановилась? • 1 — плохо • N (где N равен размеру команды) — хорошо
66. Равномерное распределение информации по команде
67. Равномерное распределение информации по команде
68. Равномерное распределение информации по команде
69. Равномерное распределение информации по команде
81. ДОКУМЕНТАЦИЕЙ ДОКУМЕНТАЦЕИ
82. Что на самом деле происходит в индустрии
83. Что на самом деле происходит в индустрии
84. Что на самом деле происходит в индустрии
85. • «Документация покрывает от силы 40% кодовой базы» Что на самом деле происходит в индустрии
86. • «Документация покрывает от силы 40% кодовой базы» • «У нас вообще нет документации, хотя все понимают, что она нужна» Что на самом деле происходит в индустрии
87. • «Документация покрывает от силы 40% кодовой базы» • «У нас вообще нет документации, хотя все понимают, что она нужна» • «Документация есть, но в последний раз она обновлялась при Медведеве» Что на самом деле происходит в индустрии
88. Почему документации нет?
89. Почему документации нет?
90. Почему документации нет?
91. 1. Всегда некогда. Почему документации нет?
92. 1. Всегда некогда. 2. Непрофильная активность для инженеров. Почему документации нет?
93. 1. Всегда некогда. 2. Непрофильная активность для инженеров. 3. Писать слова и фразы вообще сложно. Сложнее, чем код. Почему документации нет?
94. 1. Всегда некогда. 2. Непрофильная активность для инженеров. 3. Писать слова и фразы вообще сложно. Сложнее, чем код. 4. Понятно описывать сложные вещи — огромный труд (сходство с преподаванием). Почему документации нет?
95. 1. Всегда некогда. 2. Непрофильная активность для инженеров. 3. Писать слова и фразы вообще сложно. Сложнее, чем код. 4. Понятно описывать сложные вещи — огромный труд (сходство с преподаванием). 5. Для кода есть паттерны и best practices. Для документации их нет. Почему документации нет?
96. Что же делать?
97. • Инженерам нужно перестать писать документацию Что же делать?
98. • Инженерам нужно перестать писать документацию • И нанять для этого специального человека Что же делать?
99. Технический писатель
100. Технический писатель
101. Специалист, умеющий: • целеполагать • проектировать • и писать документацию. Технический писатель
102. Специалист, умеющий: • целеполагать • проектировать • и писать документацию. Технический писатель
103. Специалист, умеющий: • целеполагать • проектировать • и писать документацию. Технический писатель
104. Технический писатель
105. • Любит писать, получает от этого удовольствие Технический писатель
106. • Любит писать, получает от этого удовольствие • Любит объяснять и доносить информацию Технический писатель
107. • Любит писать, получает от этого удовольствие • Любит объяснять и доносить информацию • Пишет емко и понятно Технический писатель
108. Технический писатель: как получает инфу?
109. • Общение с инженерами Технический писатель: как получает инфу?
110. • Общение с инженерами • Самостоятельное изучение продукта (подергать API, попользоваться библиотекой) Технический писатель: как получает инфу?
111. • Общение с инженерами • Самостоятельное изучение продукта (подергать API, попользоваться библиотекой) • Чтение кода Технический писатель: как получает инфу?
112. Технический писатель
113. Технический писатель
114. Технический писатель • Технический бэкграунд
115. Технический писатель • Технический бэкграунд Computer science, программная инженерия, опыт программирования…
116. Технический писатель • Технический бэкграунд Computer science, программная инженерия, опыт программирования… • Гуманитарная жилка
117. Технический писатель • Технический бэкграунд Computer science, программная инженерия, опыт программирования… • Гуманитарная жилка Хороший письменный стиль, умение объяснять…
118. Технический писатель
119. • Два высших образования? Технический писатель
120. • Два высших образования? • На самом деле хотя бы одно Технический писатель
121. • Два высших образования? • На самом деле хотя бы одно • Гуманитарий, который самостоятельно добрал айтишной фундаментальщины Технический писатель
122. • Два высших образования? • На самом деле хотя бы одно • Гуманитарий, который самостоятельно добрал айтишной фундаментальщины • Технарь, который [почему-то] любит и хочет писать буквы и слова Технический писатель
123. Технический писатель как карьерная опция
124. • Молодая, набирающая популярность IT-профессия Технический писатель как карьерная опция
125. • Молодая, набирающая популярность IT-профессия • Компании стремительно осознают важность документации Технический писатель как карьерная опция
126. • Молодая, набирающая популярность IT-профессия • Компании стремительно осознают важность документации • Техписателя с айтишным образованием готовы оторвать с руками Технический писатель как карьерная опция
127. Технический писатель: где поучиться?
128. • Университетских специальностей [почти] нет Технический писатель: где поучиться?
129. • Университетских специальностей [почти] нет • Онлайн-курсы Технический писатель: где поучиться?
130. • Университетских специальностей [почти] нет • Онлайн-курсы • documentat.io/courses Технический писатель: где поучиться?
131. • Университетских специальностей [почти] нет • Онлайн-курсы • documentat.io/courses • IT-образование и умение внятно писать = позиция мидл-техписателя в большинстве российских компаний Технический писатель: где поучиться?
132. Не хочу в техписатели, хочу писать код
133. • Скорее всего, вам придется писать документацию Не хочу в техписатели, хочу писать код
134. • Скорее всего, вам придется писать документацию • Стоит немного поучиться паттернам документирования Не хочу в техписатели, хочу писать код
135. • Скорее всего, вам придется писать документацию • Стоит немного поучиться паттернам документирования • и вообще научиться эффективно складывать слова в предложения Не хочу в техписатели, хочу писать код
136. Что почитать разработчику о документации
137. «Взгляд на документацию с точки зрения бизнеса» Что почитать разработчику о документации
138. «Взгляд на документацию с точки зрения бизнеса» What nobody tells you about documentation Что почитать разработчику о документации
139. «Взгляд на документацию с точки зрения бизнеса» What nobody tells you about documentation c4model.com и arc42.org, методологии документирования архитектуры Что почитать разработчику о документации
141. Заменит ли ChatGPT техписателей?
142. Заменит ли ChatGPT техписателей?
143. Заменит ли ChatGPT техписателей?
144. Заменит ли ChatGPT техписателей? • Документация опирается на закрытое знание о проприетарной системе
145. Заменит ли ChatGPT техписателей? • Документация опирается на закрытое знание о проприетарной системе • Вы пускаете чужой AI в вашу кодовую базу?
146. Заменит ли ChatGPT техписателей? • Документация опирается на закрытое знание о проприетарной системе • Вы пускаете чужой AI в вашу кодовую базу? • Если да, то, скорее всего, он уже пишет код за вас
147. Заменит ли ChatGPT техписателей? Да. Примерно тогда же, когда и программистов.
149. • Документация сохраняет знания о системе и удешевляет обмен ими • Техписатель — специалист, снимающий документационную нагрузку с инженеров • Любите писать? Приходите в эту профессию • Поучитесь у экспертов: documentat.io/courses Подытожим
150. Нужно ли писать документацию? Семëн Факторович, documentat.io factorized