Still don't get why people are constantly surprised at the difficulty of building a career and having kids. Having kids is a life choice with upsides (awesome upsides imo) and downsides. Same goes for having a career in tech. Wanna do both? You can, but YOU WILL have to work 2x harder than all the people doing only one of these (arguably, you'll also get a lot more).
In my opinion this is a very important battle, even if this will be a 100% internal API. Think about the possible scenario - no one touches one of the endpoints for 18 months. A new developer comes in and wants to use it. There are no docs and no one remembers what's going on there. == mess.
depending on this API, it could just be easier to look at the code. Seriously, if it is just exposing some database tables, then I don't necessarily always see the point of extra documentation. With extra docs you have to answer:
* Who writes the docs?
* Who reads the docs?
* Where are the docs?
* When are the docs written?
* How are the docs written?
Basically, unless you have a dead-simple process, or a docs champion, you've just created another project. If you can answer these questions:
* Who writes the codez?
* Who reads the codez?
* Where are the codez?
* When are the codez written?
* How are the codez written?
Then the simplest thing may be "just read the code"
I'd argue that this should go the other way around. Your developers should be creating the 'docs' - the API design and boilerplate, before programing it.
If they actually sit down and design the API before setting of to write the code you'll end up with:
(a) the documentation you want.
(b) an API that this designed consistently and consciously.
Would you let your front end developers build something without at least a wire frame / functional design?
Good point. How can you build an API if you don't know what data to return anyway? Designing a model is part of the job and could be documentation by itself. Thanks!
