Why good documentation is important

Blog Post created by lkilligrew on Aug 8, 2016

My role in Developer Integrations is a little different from my colleagues. I was hired in 2012 as their first-ever technical writer. My initial challenge was to rewrite all of our integration guides for the MercuryPay platform, which were criticized as difficult to follow. Four years and thousands of pages later, they are praised.


Technical writing is one of my passions; my motto is, “anything can be made simple, and it’s really hard to make things simple.” Think of the last time you tried to assemble something, like a piece of furniture from the store, and how hard it was. One time my husband and I bought a computer desk for his sister. Between the two of us it took over 4 miserable, cursing hours to put the thing together. The assembly instructions were horrid, and neither of us had ever assembled furniture before. As we worked, we eventually got the hang of it, and I realized the instructions were not well organized and did not offer any explanation beyond “put thingamajig A into hole B”. If we’d known why we were doing that, we would have reached that “aha” moment much earlier and would have been able to put the desk together in about 45 minutes.


That’s the problem with most technical guides. They’re usually a long laundry list of field definitions – name, type, length, and an often cryptic definition about what the field is for. There is very little context on why one would use that field in constructing a transaction request other than “required” or “optional”. Beyond that the programmer is on their own.

My approach is different. You’ll find complete explanations in our guides about the “bigger picture” – how to construct the whole payment request under a given set of circumstances; why certain fields are required and how the values in those fields are used to generate transaction responses; nuances to be aware of, etc. For instance, we have two ways to cancel a Sale – Void and Reversal. Void is an actual trancode, but reversal is not. Both cancel a transaction and return funds to the card, so what’s the difference? Our earlier explanations were dense and confusing, causing lots of phone calls and emails. In our latest guide we’ve straightened all that out. Simply put, a Void goes to the processor and can take several days to complete, but if the Void transaction includes two additional fields, it reroutes the request to the card issuing bank and will settle in less time. By adding this explanation, our programmers understand the context, and confusion/frustration is thwarted.


All of our integration guides are available on Vantiv O.N.E., and I welcome feedback. Nothing is ever perfect, so if you have a question, or would like something added to the guides, let us know. We are here to make your job easier – it really is a partnership!