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