PageRenderTime 4ms CodeModel.GetById 2ms app.highlight 13ms RepoModel.GetById 1ms app.codeStats 0ms

/duckduckhack/resources/faq.md

https://github.com/DavidMascio/duckduckgo-documentation
Markdown | 163 lines | 92 code | 71 blank | 0 comment | 0 complexity | b7a157c5ccfa75fe35bdd805e31763ff MD5 | raw file
  1# DuckDuckHack FAQ
  2
  3## General FAQ
  4
  5### Why should I make instant answers?
  6
  7We hope you will consider making DuckDuckGo instant answers to:
  8
  9- Improve results in areas you personally search and care about, e.g., [programming documentation](https://duckduckgo.com/?q=perl+split), [gaming](https://duckduckgo.com/?q=roll+3d12+%2B+4) or [entertainment](https://duckduckgo.com/?q=xkcd).
 10- Increase usage of your own projects, e.g., data and [APIs](https://duckduckgo.com/?q=cost+of+living+nyc+philadelphia).
 11- Attribution [on our site](https://duckduckgo.com/goodies.html) and [Twitter](https://twitter.com/duckduckhack) (working on more).
 12- See your code live on a [growing](https://duckduckgo.com/traffic.html) search engine!
 13- Learn something new.
 14
 15### What if I'm not a coder at all?
 16
 17If you don't code at all and you've ended up here, please go over to our [instant answers ideas forum](http://ideas.duckduckhack.com/) where you can suggest and comment on instant answer ideas. For instance, identifying the best sources to draw from is extremely important but not many developers know the best sources, which is where you come in! Similarly, you can submit [issues about current instant answers](https://github.com/duckduckgo/duckduckgo/issues?direction=desc&sort=created&state=open). Both of these activities are very valuable and will help direct community efforts.
 18
 19If you're a business and want your data to be utilized, adding your service to [ideas.duckduckhack.com](http://ideas.duckduckhack.com) is a great way for your API to get picked up by a developer and integrated into the search engine.
 20
 21### Can you help me?
 22
 23Of course! Here are the easiest ways to contact someone who can help answer your questions:
 24
 25- Write us publicly on the [discussion list](https://www.listbox.com/subscribe/?list_id=197814).
 26- Write us privately at open@duckduckgo.com.
 27
 28### What if I don't know Perl?
 29
 30If you don't know Perl, that's OK! Some instant answer types ([Fathead](https://github.com/duckduckgo/duckduckgo-documentation/blob/master/duckduckhack/fathead/fathead_overview.md), [Longtail](https://github.com/duckduckgo/duckduckgo-documentation/blob/master/duckduckhack/longtail/longtail_overview.md)) don't require the use of Perl. Also, if you know PHP, Ruby, or Python you should be able to write a [Goodie](https://github.com/duckduckgo/duckduckgo-documentation/blob/master/duckduckhack/goodie/goodie_overview.md) in Perl pretty easily using [this awesome cheat sheet](http://hyperpolyglot.org/scripting).
 31
 32### Do you have any instant answer ideas?
 33
 34Yup! We maintain [a growing list](http://ideas.duckduckhack.com/). There are also improvement ideas for [Goodies](https://github.com/duckduckgo/zeroclickinfo-goodies/issues), [Spice](https://github.com/duckduckgo/zeroclickinfo-spice/issues), [Fathead](https://github.com/duckduckgo/zeroclickinfo-fathead/issues) and [Longtail](https://github.com/duckduckgo/zeroclickinfo-longtail/issues).
 35
 36### How do I note that I've started on something?
 37
 38In your initial pull request, please note the link on the [idea list](http://ideas.duckduckhack.com/). We'll move it to the "in process" bucket for you.
 39
 40### Where I can report instant answer bugs?
 41
 42Submit GitHub issues in the [appropriate repo](http://github.com/duckduckgo).
 43
 44### What if there are instant answer conflicts?
 45
 46Instant answer sources often compete to answer the same searches. In a lot of cases, the experience can be blended together so that the user is shown answers from more than one source. Our long-term vision for instant answers involves multiple sources used in that way.
 47
 48There are times, though, where one source does a drastically better job of answering a particular query set. In those cases, the source used for those queries should be the source most capable of delivering the best possible user experience. Our community evaluates those in a few ways: 
 49
 50- Consistent performance (is the service reliable?) 
 51- Speed (does the service return results fast enough?) 
 52- Quality (does the service answer the queries better than any other service?)
 53
 54If you think you have a source that is better, let's talk about it on the [DuckDuckHack e-mail list](https://www.listbox.com/subscribe/?list_id=197814).
 55
 56### Why isn't my instant answer in the [DuckDuckGo Instant Answers API](https://api.duckduckgo.com)?
 57
 58If your instant answer is spice or longtail, sometimes we can't expose it through the API for licensing reasons (e.g., the WolframAlpha instant answer), but our
 59over-arching goal is to make all of our instant answers available on their own.
 60
 61### Can I do something more complicated?
 62
 63Maybe. There are a bunch more internal interfaces we haven't exposed yet, and we'd love to hear your ideas to influence that roadmap.
 64
 65### What's the roadmap?
 66
 67Here's what we're working on (in roughly in this order):
 68
 69- better testing/file structure for spice instant answers.
 70- better JS interface for spice instant answer callback functions.
 71- better attribution.
 72- embedding instant answers.
 73- better testing/file structure for fathead instant answers.
 74- more defined structure for longtail instant answers.
 75- better testing for longtail instant answers.
 76
 77### Are there other open source projects? 
 78
 79Yes! Check out the other repositories in [our GitHub account](https://github.com/duckduckgo). You can email open@duckduckgo.com if you have any questions on those.
 80
 81### Can I get the instant answers through an API?
 82
 83Yes! Check out the [DuckDuckGo API](https://api.duckduckgo.com). Our goal is to make as many instant answers as possible
 84available through this interface. Fathead and goodie instant answers are automatically syndicated through the API, and Spice and Longtail are selectively (due to licensing complications) mixed in.
 85
 86### Can I talk to you about a partnership idea?###
 87
 88Sure -- check out [our partnerships page](http://help.duckduckgo.com/customer/portal/articles/775109-partnerships).
 89
 90## Goodie FAQ
 91
 92### Can Goodie instant answers make network requests?
 93
 94No. If you are trying to use an API, you should consider creating a Spice instant answer instead.
 95
 96### Can Goodie instant answers include the user's query string?
 97
 98Yes. **However**, they must be handled *very* carefully. User-supplied strings create a lot of potential for [cross-site scripting attacks](https://www.owasp.org/index.php/Cross-site_Scripting_%28XSS%29).  While the platform attempts to mitigate these issues in pure ASCII responses, HTML responses should **never** include a raw query string. It is safest to return only data which is generated by your Goodie itself.
 99
100## Spice FAQ
101
102### I want to use 'X' API, but it doesn't have an endpoint for 'Y'. What should I do?
103
104Email them! - If you explain what it's for, they might be willing to create and endpoint for you! If not, it's probably best to find another API.
105
106### The API provides both HTTP and HTTPS endpoints; which should I use?
107
108We prefer to use **HTTP endpoints** because the reduced connection setup time allows us to provide faster answers to the user.  Note that the end-user's query will still be secure in transit, because it is proxied ( e.g. https://duckduckgo.com/js/spice/movie/mib ) through an HTTPS connection to the DuckDuckGo servers.
109
110### Can I use an API that returns XML?
111
112Sorry, but **not right now**. XML support is coming soon.
113**Note:** If an API supports both JSON and XML, we *stronly enourage* you to use **JSON**.
114
115### Can I use an API that returns HTML or a String?
116
117Sorry, but **no**. We currently don't support HTML or plain text API's.
118
119### Can I use the 'X', 'Y' or 'Z' JavaScript library?
120
121Probably not. Maybe, if it is very small, but we prefer that no third party, extra libraries are used. ***Please*** ask us first before writing an instant answer that is **dependent** on an extra library - we don't want you to waste your time and energy on something we can't accept!
122
123### Can I use Coffeescript?
124
125No.
126
127### What about...
128
129Nope. Just use JavaScript, please and thanks :)
130
131## Fathead FAQ
132
133### How can I test my output file?
134
135Unfortunately, there is no way for contributors to do so. But if you've gotten that far, we want to hear about it! Please open a pull request and we'll help you through the testing process.
136
137### What can go in a result abstract?
138
139A result abstract can be either plain text (generally one readable sentence, ending in a period), or HTML. Special care needs to be taken when abstracts contain HTML. Please let us know ahead of time if you are planning to use HTML.
140
141(This section is still growing! Know what should go here? Then **please** [contribute to the documentation](https://github.com/duckduckgo/duckduckgo-documentation/blob/master/CONTRIBUTING.md)!)
142
143## Longtail FAQ
144
145(This section is coming soon! Know what should go here? Then **please** [contribute to the documentation](https://github.com/duckduckgo/duckduckgo-documentation/blob/master/CONTRIBUTING.md)!)
146
147## DuckPAN FAQ
148
149### How do I install a missing Perl dependency?
150
151Any Perl module (.pm file) that has external Perl dependencies will load them with a `use` statement. Typically these statements are located near the top of the file. For example, the Factors Goodie (`lib/DDG/Goodie/Factors.pm`) loads the module `Math::Prime::Util`. If this is not installed on your system, DuckPAN will not be able to use the Factors Goodie and you will likely see an error or warning.
152
153In order to install any missing dependencies you can use cpan or cpanm like so:
154
155```perl
156cpan install Math::Prime::Util
157# or
158cpanm Math::Prime::Util
159```
160
161Alternatively, if you would like to install all the dependencies for the repo (e.g. zeroclickinfo-goodies), you can run `duckpan installdeps`. Please note that installing all the dependencies will take **several minutes** to install as there are many dependencies.
162
163![dependency](https://raw.githubusercontent.com/duckduckgo/duckduckgo-documentation/master/duckpan/assets/dependency.png)