Comment by zer00eyz

> It turns out, to describe a system in enough detail to implement the system, you need to use a programming language.

Go back to design patterns. Not the Gang of Four, rather the book where the name and concept was lifted from.

What you will find is that implementations are impacted by factors that are not always intuitive without ancillary information.

It's clear when there is a cowpath through a campus, and the need for a sidewalk becomes apparent. It's not so clear when that happens in code because it often isnt linear. It's why documentation is essential.

"Agile" has made this worse, because the why is often lost, meetings or offline chats lead to tickets with the what and not the why. It's great that those breadcrumbs are linked through commits but the devil is in the details. Even when all the connections exist you often have to chase them through layers of systems and pry them out of people ... emails, old slack messages, paper notes, a photo of a white board.