При проектировании часто возникает потребность разбираться в реализации сторонних систем. Причина — необходимость переиспользования их данных и/или функциональности. Погружение в документацию таких систем, что греха таить, не всегда оказывается простой задачей.

На текущий момент я сформулировал следующие контринтуитивные факты, осложняющие этот процесс.

🤭 Авторы документации не всегда знают, как работает их система
С учётом того, что практика водопадной разработки становится редкостью, а сложность ПО растёт, многие принятые решения могут остаться "в головах" аналитика и других членов команды (даже если они изначально планировали подразгести завалы и описать позднее). Более того, пройдёт время и детали забудутся. Печальное следствие: уточнение вопросов по документации может увести вас по ложному пути и утвердить в ошибочном знании.

📚 Большой объём документации это не всегда хорошо
Исходя из моего опыта, неточностями часто страдает именно самые хорошо задокументированные системы. Возможной причиной может быть то, что такая документация ориентирована в большей степени на внутреннего потребителя и оттого в ней упущено общее, а сразу идут частности. Собрать целостную картину из массивного описания деталей стороннему наблюдателю становится сложно.

Другая причина. Почти всегда новая версия документации разрабатывается на основе предыдущей, и автором не во всех местах могут быть качественно внесены правки (не актуализировано название поля, приложенный макет экранной формы отражает промежуточное видение, JSON с примером обновлён, а пояснение к нему — нет и т.п.)

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

🤯 Документация разработчиков сервиса может не быть полной для потребителя
Казалось бы, этот пункт противоречит ранее сказанному. Но нет. Разные производственные цели у 2-х смежных команд (даже если речь идёт о командах поставщика и потребителя одного и того же сервиса) могут приводить к появлению моделей, не подходящих для смежников. Например, если для полноценной работы с сервисом потребителю дополнительно требуется выстроить взаимодействие с третьей стороной, то этот факт может быть упущен во внутренней документации поставщика сервиса (подобный пример я разбирал в видео).