How to Write a Zotero Translator:
A Practical Beginners Guide for Humanists
By: Adam Crymble
Chapter 2: General Troubleshooting Guidelines
This Chapter
Before we start, you should be aware: you will get frustrated — at least once. Here are a few tips to help you ease the frustrations and solve your problems.
Search Engines:
If you run into difficulties when writing computer code the great news is: the answer to almost any problem can be found online. All computer programmers have needed help at one time or another, and given their love for computers, most sought that help online. Lucky for you, that means that most of the questions they asked — and the subsequent answers — are still floating around the internet.
This means the internet is often your best resource for finding help. If you run into a problem, the first thing you should do is type your problem into a search engine. More often than not someone has already asked your exact question, and someone else has provided an answer. You might even find entire websites dedicated to solving your particular problem. As far as coding goes, Zotero translators are quite basic; you will not come across a problem when writing a Zotero translator that no one has encountered before.
Likewise, if you encounter an error message you don't understand, cut and paste that error message into a search engine and surround it with quotation marks. You will likely find dozens of explanations why this error appeared and how to fix it.
The more specific you can be about your problem, the better the results you will find. Don't be discouraged if you don't find the answer on your first search. Rephrase the search terms and try again.
Online Tutorials:
Your second best option is W3Schools tutorials. W3Schools has step-by-step tutorials for nearly every internet-related programming language. Particularly helpful for this project are:
- W3 Schools HTML tutorial
- W3 Schools HTML DOM tutorial
- W3 Schools JavaScript tutorial
At W3Schools, you can find great reference charts that will show you at a glance all the different capabilities of JavaScript and HTML. These will come in handy when you want to do something and can't remember how.
Apart from W3Schools, you can find many other tutorials online. Try typing in what you want to learn into a search engine and you will likely find a tutorial. Keep in mind that many tutorials teach you how to accomplish a specific task and may not teach you exactly what you're looking for.
Forums:
If you've Googled it, Yahoo'd it, looked it up on the W3Schools reference charts and tried various combinations of teas, coffees and energy drinks to no avail, you're going to need to ask for help. There are numerous internet forums to which you can turn for this; just find a forum you like. Here are a couple to get you started:
Webdeveloper.com
If you are looking for a good forum, the JavaScript forum at WebDeveloper.com is excellent, especially for code-related questions.
If you can't figure out why you are getting a particular error message, or why you can't get information from point A to point B, this is the forum for you. At any given time there are over one hundred people logged into the forum just waiting to answer your question. If you post your problem here in a courteous manner, with a little bit of luck you will have a solution within a couple of hours.
It may not be the instant gratification we've come to expect, but don't forget, these people are volunteering to help you, and most probably if you're desperate enough to ask for help, you could use a few hours away from the keyboard anyway.
Zotero Forums
If your question is something specific to Zotero, such as "why can't I put anything in the field Loc. in archive?" the helpful men and women at WebDeveloper.com will have no idea how to answer your question. Instead, post it to the Zotero forums. Don't expect an answer as quickly as you would get on a more popular forum — there are only so many Zotero programmers to go around. You should get an answer in a couple of days as long as you're clear in your description of your problem.
Asking Good Questions
Clarity and specificity are your friends when it comes to asking for help on a forum. The people who read forums and offer their expertise are busy; make it easy for them by carefully thinking out your problem before you ask. Likewise, make sure you are asking a specific question to a narrowly defined problem.
For example, don't post something like: "Why won't my translator work?"
Instead, try: "Why am I getting a syntax error when I try to Push a value into an Object?"
Always post the relevant section of your code (and only the relevant section of your code) along with your question. This will make it easier for the experts to help you solve your problem. If the answer you get does not do the trick and you are still stuck, be polite and try rephrasing the question. Remember, don't bite the hand that feeds you; these are volunteers and they're trying to help you!
Debugging
To help you ask good questions you'll learn how to use the Zotero.debug() method in Chapter 6. This will let you figure out exactly which part of your code is not working. Until then, keep the following in mind:
When fixing problem code, only change one thing at a time. If you are working on a section of code that has several issues, fix one problem and retry the code before moving on. Sometimes if you make three or four changes before retrying the program, you will inadvertently cause another unexpected problem. This can make you think your fix was incorrect, when in fact only the last change you made was wrong. Change one thing and make sure it works before moving on and you will prevent a lot of confusion.