Although my official job title is “Software Engineer,” my API knowledge makes me an honorary member of the tech support team. More often than not, I read a problem and don’t have enough information to answer it properly. This requires me to respond asking for more formation. Usually one or two more back-and-forth sessions are needed before the question is finally answered. This process is a wasteful, especially when different time zones are involved. If you figure that each back-and-forth takes 24 hours, there is a definite benefit to reducing these round-trips.
So here is a list of things you can do to make the process more efficient. The goal is to provide all the needed information upfront so that I don’t have to go back and ask you to elaborate in more detail.
DO... include the Vault product and version
Is it Vault Basic? Vault Professional? Is is the 2013 version? Each product has a different feature set and the API may change between release years.
DON’T... use the phrase “It doesn’t work”
That statement is way too vague. You need to be more specific like “it crashes the program” or “it locks up and I have to restart the app” or “it times out” or “it returns error 303”
DO... include the error code
If the server returns an error, don’t just say “the server throws an error”. Tell me what the error code is. Don’t leave me in suspense. I even have some code snippets you can use to extract the error and restriction codes (if any).
DON’T... provide too much source code
Sometimes people will post their entire project and expect me to debug it. That’s not a good use of anybody’s time. If you are going to include source code, it should be isolated to a single function at most.
DO... isolate the line of code that fails
If you are sending a block of code and are getting Exceptions, you need to indicate clearly which line is causing the breakage.
DO... take screenshots
It’s amazing how much information is conveyed in a screenshot. Even if the Vault is in a different language, I can usually figure out what is going on based on the icons and dialogs. Videos are great too. If you find yourself taking 4 or more screenshots, it may be easier to just record a video.
DO... use Exception.ToString()
ToString is the best thing to happen to debugging since the print statement. Don’t be afraid to use it and include the full stack trace in your problem report. Even if you don’t understand it all, it may make sense to me since I have access to the Vault source code.