It would be cool if devs would have the time to update the documentation too, but this is not the case in most projects. I will bookmark the project to use it only at the design phase of a new API, before creating the mockup server/clients.
I would recommend a more realistic and pragmatic approach, as your unit tests is a documentation of your code, a series of API tests (like a Postman collection) should be enough for any API. It can also be used in the Integration pipeline so you cannot "forget" to update it.
I think that documentation is needed always to ensure the health of the project, sometimes even more than tests. In my actual company, we were documenting at least the necessary things and we are losing it day by day.
The main problem, in my opinion, is that sometimes nobody reads these docs for months until someone new comes to the team or you have to reuse some of that features, and probably by then that info would be obsolete.
I agree with you that is hard to maintain documentation.
In my next article, I'll be using Dredd for test these docs against the API server ensuring by that way the info is up to date. So, at the end, this docs will be more useful ensuring even code coverage.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
It would be cool if devs would have the time to update the documentation too, but this is not the case in most projects. I will bookmark the project to use it only at the design phase of a new API, before creating the mockup server/clients.
I would recommend a more realistic and pragmatic approach, as your unit tests is a documentation of your code, a series of API tests (like a Postman collection) should be enough for any API. It can also be used in the Integration pipeline so you cannot "forget" to update it.
Thanks for the comment!
I think that documentation is needed always to ensure the health of the project, sometimes even more than tests. In my actual company, we were documenting at least the necessary things and we are losing it day by day.
The main problem, in my opinion, is that sometimes nobody reads these docs for months until someone new comes to the team or you have to reuse some of that features, and probably by then that info would be obsolete.
I agree with you that is hard to maintain documentation.
In my next article, I'll be using Dredd for test these docs against the API server ensuring by that way the info is up to date. So, at the end, this docs will be more useful ensuring even code coverage.