📇5 причин писать дизайн доки

В Канве, за короткое время в этой компании я написал такое количество дизайн документов, сколько не писал за всю свою карьеру.

По какой-то внутренней причине я полюбил этот бюрократический процесс. Мне нравится, когда документ легко читается, правильно оформлен и отполирован так, что комар носа не подточит.

Что такое Дизайн Документ?

Это детальный план, который описывает, как будет построена система. Он помогает всем участникам проекта, инженерам, техлидам, менеджерам понять, что нужно сделать и как это будет реализовано, до того, как начнется разработка.

Другими словами, если вы планируете делать сложный проект и существует несколько возможных вариантов реализации, то лучше описать все способы на бумаге, предложить наилучший, подсветить риски и возможные проблемы, а также сколько это займет времени.

Подготовил для вас шаблон такого документа для наглядности.

Именно поэтому сегодня перевод статьи “Reasons to write design docs”.

Дизайн доки заставляют думать

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

Совместная работа улучшает качество документа

Всегда полезно запрашивать ревью у коллег на свой дизайн документ. Свежий взгляд быстро подмечает очевидные ошибки. Рецензенты могут указать на неясные моменты или недостатки в дизайне и дать ценные отзывы.

Дизайн доки - это база знаний

Когда решения принимаются устно, то вы становитесь по сути хранителем этих знаний. Вашим коллегам и другим командам возможно было бы полезно знать о проекте, над которым вы работаете. Когда в компании и в команде есть культура написания технический документов, это дает возможность быть в курсе архитектурных решений и делиться знаниями между командами.

Кто виноват и что делать?

В разработке часто меняется важность, то что было неважным пару лет назад, сейчас может стать критически важным куском кода. Без документации сложно понять, почему были приняты те или иные решения. Это как забор посреди поля, никто не знает почему он там стоит, но все уверены, что была веская причина (и возможно она есть). Можно попытаться восстановить контекст через коммиты, таски и коллег, но часто это не дает полного представления. Дизайн документы позволяют хранить историю проблем и их решений, и помогают новым инженерам избежать наступания на грабли.

Дизайн документ устаревают

Дизайн документ даёт лишь приблизительное представление о том, как система работала в определённый момент времени прошлого, но многое могло измениться с того времени. Документ представляет собой намерение, но это не значит что все будет или было реализовано с 100% точностью. Чтение прошлых дизайн документов помогает понять, как другие инженеры видели систему, с какими проблемами боролись и к чему стремились.

➡️Ссылка на статью
https://ntietz.com/blog/reasons-to-write-design-docs