Who Writes Kong Documentation?


#1

We’re trying to improve our API documentation and find Kong documentation is well written. Who writes your API documentation? Technical writers? Engineers? What kind of background do they have - senior writers? development engineers? fresh out of school? Do you do usability testing on your documentation?
We’d like to emulate your documentation style.


#2

Community member here, its very neat the way Kong does it, see here:

Where you have a github repo and internal employees as well as external community members like myself can also update and PR changes to their documentation as we push code changes forward, then they redeploy the app after changes have been made and poof, the site is now up to date :slight_smile: . I have not seen many teams do a better job on such a setup honestly.


#3

So all the documentation is open source? Written by engineers contributing code?
Hmm, why does it work so well for Kong and not other open source communities?


#4

Oh and thank you so much for responding!


#5

Hello, Kong Inc. staff member here.

The bulk of our documentation was and is written by Kong Inc. employees. We often write documentation at the same time that features are being coded, and docs are generally written by the engineers doing the feature coding (or by their teammates).

We don’t have any dedicated tech writers or documentation staff. Instead, every engineering team at Kong has documentation part of their Definition of Done.

We don’t do any formal usability testing - however, our own Customer Success staff use our public-facing docs as their primary source of technical information, so perhaps you could say we drink our own champagne? (We like drinking :champagne: much more than eating :dog: food!)

Docs are… hard :slight_smile: . Doing it this way ^^ is our ideal, but we don’t always meet our goals - sometimes docs get written or updated well after code is written, sometimes even after we ship new code.

As @jeremyjpj0916 points out, our community increasingly contributes to our docs - I personally believe that this occurs partly because we’ve invested so much in docs in the past; community members are much more likely to make little improvements when only little improvements are necessary. If you have “bad” docs to start with, it is much harder for community members to contribute, as there is so much to fix!