Who's the audience for the docs?

Last Update: 16.04.2018. By Jens in Developers Life | Learning | Newsletter

There’s a confluence for the project from stone age I am helping out. Its aim is to provide the documentation for the project. Unfortunately, it does not have a clear focus for whom it is written.
Yep, a documentation has an audience - the stakeholders. Depending on the audience, it contains slightly different information, e.g. third-party devs connecting to the system want to know how to do just that and how they can map their business use cases to the systems API; on the other hand, the internal devs are probably not interested in such details as they care for their business use cases. Same goes when the audience is non-dev too.

So in my particular case, which brought up today’s topic, we were looking for already implemented endpoints and try to figure out which one we could use or modify for our use cases at hand. The confluence had a list of all available services but with an unuseable description. The desc just stated the name of the endpoint and a simple table with all path variables and request params and their types. Yep, nothing more.

It just duplicates what could be generated by the Javadocs with the exact same information. none. It is pretty useless.

Regardless of the stakeholder, we only know it exists and certain parameters. Yet, nothing more. Not what it does, how it behaves or anything. It is definitely written for “Sure, we have written documentation.”, so the customer can check it and nobody ever reads it.

If you write documentation, be sure you know the purpose of it and who’s the target audience. Then provide that.