PageRenderTime 45ms CodeModel.GetById 38ms app.highlight 6ms RepoModel.GetById 0ms app.codeStats 0ms

/duckduckhack/resources/faq.md

https://gitlab.com/Guy1394/duckduckgo-documentation
Markdown | 170 lines | 95 code | 75 blank | 0 comment | 0 complexity | 5b109fa9932dcbe5b590cd9ccc9d1183 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, please check out our [Instant Answers Ideas Forum](https://duck.co/ideas) where you can suggest and comment on Instant Answer ideas. For instance, identifying the best sources to draw from is extremely important but developers may not know what they are. 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 the [Instant Answers Ideas Forum](https://duck.co/ideas) 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](https://duck.co/ideas). 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 [Ideas Forum](https://duck.co/ideas). We'll move it to the "in process" bucket for you.
 39
 40### Where I can report Instant Answer bugs?
 41
 42Submit a GitHub issue in the [appropriate repository](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, but our over-arching goal is to make all of our Instant Answers available on their own.
 59
 60### Can I add triggers for my language?
 61
 62We have plans to make it possible to trigger Instant Answers in many different languages. Until an internationalization mechanism is place, to uphold maintainability and consistency, **we cannot accept pull requests that add languages directly in the code.**
 63
 64### Can I do something more complicated?
 65
 66Maybe. There are a bunch more internal interfaces we haven't exposed yet, and we'd love to hear your ideas to influence that roadmap.
 67
 68### Can I create adult Instant Answers (i.e. NSFW)?
 69
 70No.
 71
 72### What's the roadmap?
 73
 74Here's what we're working on (in roughly in this order):
 75
 76- better testing/file structure for spice Instant Answers.
 77- better JS interface for spice Instant Answer callback functions.
 78- better attribution.
 79- embedding Instant Answers.
 80- better testing/file structure for fathead Instant Answers.
 81- more defined structure for longtail Instant Answers.
 82- better testing for longtail Instant Answers.
 83
 84### Are there other open source projects?
 85
 86Yes! 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.
 87
 88### Can I get the Instant Answers through an API?
 89
 90Yes! Check out the [DuckDuckGo API](https://api.duckduckgo.com). Our goal is to make as many Instant Answers as possible
 91available 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.
 92
 93### Can I talk to you about a partnership idea?
 94
 95Sure -- check out [our partnerships page](https://duck.co/help/company/partnerships).
 96
 97## Goodie FAQ
 98
 99### Can Goodie Instant Answers make network requests?
100
101No. If you are trying to use an API, you should consider creating a Spice Instant Answer instead.
102
103### Can Goodie Instant Answers include the user's query string?
104
105Yes. **However**, they must be handled *very* carefully. User-supplied strings create a lot of potential for [cross-site scripting attacks](https://duckduckgo.com/Cross-site_scripting?ia=about).  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.
106
107## Spice FAQ
108
109### I want to use 'X' API, but it doesn't have an endpoint for 'Y'. What should I do?
110
111Email 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.
112
113### The API provides both HTTP and HTTPS endpoints; which should I use?
114
115We 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.
116
117### Can I use an API that returns XML?
118
119Sorry, but **not right now**. XML support is coming soon.
120**Note:** If an API supports both JSON and XML, we *strongly encourage* you to use **JSON**.
121
122### Can I use an API that returns HTML or a String?
123
124Sorry, but **no**. We currently don't support HTML or plain text API's.
125
126### Can I use the 'X', 'Y' or 'Z' JavaScript library?
127
128Probably 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!
129
130### Can I use Coffeescript?
131
132No.
133
134### What about...
135
136Nope. Just use JavaScript, please and thanks :)
137
138## Fathead FAQ
139
140### How can I test my output file?
141
142Unfortunately, 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.
143
144### What can go in a result abstract?
145
146A 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.
147
148(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)!)
149
150## Longtail FAQ
151
152(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)!)
153
154## DuckPAN FAQ
155
156### How do I install a missing Perl dependency?
157
158Any 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.
159
160In order to install any missing dependencies you can use cpan or cpanm like so:
161
162```perl
163cpan install Math::Prime::Util
164# or
165cpanm Math::Prime::Util
166```
167
168Alternatively, 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.
169
170![dependency](https://images.duckduckgo.com/iu/?u=https%3A%2F%2Fraw.githubusercontent.com%2Fduckduckgo%2Fduckduckgo-documentation%2Fmaster%2Fduckpan%2Fassets%2Fdependency.png&f=1)