Якщо розробники - це супергерої програмної індустрії, то відсутність документації - наш криптоніт.
Келсі Хайтауер
Чотири години ранку, і ваш пейджер вмикається. Сервіс вашої компанії впав, і клієнти в паніці. Ви перегортаєте напівзнайому кодову базу, шукаючи кореневої причини. Повідомлення про помилки в юніт-тестах є розчаровуюче невизначеними, і внутрішній README складається з заголовків, за якими слідують дублюючі однослівні абзаци: [TODO].
Або можливо ваш сервіс працює чудово і стає ще краще. З'являється більше клієнтів, у них виникають питання. Так багато питань. Електронні листи і тікети в службу підтримки затоплюють вас по мірі зростання вашого сервісу, і вас все частіше відволікають від розробки на підтримку.
Більшість з нас вивчає важливість документації непростим шляхом, знаходячи її відсутньою, коли нам вона найбільше потрібна.
Добре задокументовані проекти економлять час як для розробників у проекті, так і для користувачів програмного забезпечення. Проекти без належної документації стикаються з низькою продуктивністю розробників, масштабованістю проекту, упровадженням користувачів та доступністю. Коротше кажучи: погана документація вбиває проекти.
Ми виявили, що якість документації передбачає успіх команд у впровадженні технічних практик. Ці практики, з свого боку, передбачають поліпшення технічних можливостей системи, таких як спостережливість, постійне тестування та автоматизація впровадження.
Звіт Google 2021 Accelerate State of DevOps
"Документація для розробників" розкриває процес створення великої документації для розробників, слідкуючи за командою програмістів під час роботи над запуском нового продукту. На кожному кроці ви навчаєтеся на прикладах, шаблонах і принципах того, як створити, вимірювати і підтримувати документацію.
Навчіться створювати документацію, яка робить вас та ваших користувачів більш продуктивними.
Ця книга робить для документації те, що The Phoenix Project робить для DevOps - вона робить ваші амбіції досяжними.
Енн Джентл, авторка Docs Like Code
Comments