
You Aren't Going to Need It – Yet - geewee
https://www.gustavwengel.dk/yagni-yet
======
Etheryte
> In hindsight, the right call here would be to write the documentation at the
> end, when the API had stabilized.

This is unrealistic and will set you up for failure in multiple ways. For
starters, no project beyond weekend lullabies will see a point where the spec
is final. You may bump your API version from v1 to v2 and v3, but at the end
of the day, there isn't going to be one big "now we're done" moment.

Even if there was, how do you expect 1) someone to consume endpoints until
then and 2) document the endpoints once that moment of reckoning arrives? No
API lives in isolation. Even if you're building a simple CRUD application, you
will have other parts of your application that will need to interface with
your endpoints. Without documentation, that's not going to happen without
incredible friction and waste of resources.

Even if you somehow dig through the integration issue, documenting things
after the fact is not realistic. When you write code, you know what it does
and how to use it. Not so much if you come back to it a month, a year, or
possibly many years from now. Documentation is there to cover both the basic
use as well as any nuances your API may involve. You're going to lose all of
the latter and most of the former if you separate writing the endpoint from
documenting it.

