So how complete should API documentation be?

Now, this is a very specific post.

If I do go generic I shall quit writing.

We had an interesting discussion recently or rather a few discussions in different formats regarding api documentation. In this case possibly the only type of documentation to go with the product. The complexity of the decision comes from the fact that the only current api client team works closely with us and does not require comprehensive documentation, however it is anticipated that other teams will have to use the api in the future.

Some people made a point that we should do as much as possible as we go to avoid accruing of technical debt and I was happy to agree with that.

Others said that we need to find out more about what the customer wants before we proceed and therefore as a start we should do nothing.

The consensus was that we can't spend too much time if the business does not agree on it and we can't do absolutely nothing since we have at least one client to use the api.

While that gave us some options the interesting bit I found was outside this discussion or during the follow-up chat.

The real question should be how much each option costs. If we do the documentation as we go we estimate to spend an average of 15 pair minutes per user story and with about 250 stories related to api calls and estimated at least one additional change (once created) per story that would amount to about 125 pair hours or 250 individual hours. It was noted that while coding without testing first these days is rather the norm however api documentation is not exactly in the same category and besides there is a difference in the level of documenting.

So let's look at another option - suppose we only invest about 16 pair hours to automate some minimal api documentation and have a short handover to the api client team of about 5 minutes per developer per user story which amounts to about 30 individual hours or 62 hours all together. The handover is guaranteed to be short due to our api client team members having access to the api source code, all tests and having been involved in most of the initial beta work.

Then with expected number of total api calls of less than 100 we estimated that a technical documentation specialist who begins as soon as we have relatively stable api calls should require no more than 15 days in total to complete a comprehensive documentation which is likely to be better read than what the team will create (due to specialist skills). The assumption is that the tech documentation specialist will use the automatically generated documentation and may require some conversation - estimated at about 10 minutes of developer time per api call. This amounts to a total of about 200 individual hours.

So even though this is based on many assumptions and estimations it is obvious that sometimes the cost of maintaining the change of api documentation manually could be more expensive than getting help from a specialist in that area for relatively short amount of time and otherwise providing a minimum level of technical documentation. Well that might be wrong. Before this conversion I would have always suggested option one but after it I would be happy to evaluate the context and look at all the available options.