Ask HN: How to Improve our API's documentation

Hello, We have an ReSt API that have been in use internally & now we have started opening it for our partners.

I have done the initial documentation by parsing our server logs to get the params, then tried the requests in POSTMAN. Once I had the params & responses, I documented them on http://developers.punchh.com/

Now, the docs there are 90% correct but sometimes they are out-of-date, wrong or have grammatical/typos in them which I fix but there is little bandwidth. I am wondering if I should outsource this work to technical writer(freelance/contract) to make sure API docs are solid as the will work on it dedicatedly vs my team who's primary focus writing code.

However, I am still not sure if this a good idea. how do other companies make sure that their API documentation is awesome? Looking for some advice on how to improve the API docs to they are easier to read:

URL: http://developers.punchh.com/