duckduckgo / duckduckhack-docs

DuckDuckHack Instant Answer documentation for developers

This repo is now archived

DuckDuckHack went on maintenance mode in 2015 and we aren't in a position to continue it. This repo hasn't been maintained subsequently and so we are archiving it.

Need to report a bug?

If you find a bug or relevancy issue, the best way to report this is via the Feedback button on the DuckDuckGo.com search results page. These issues are compiled and reviewed daily.

Have a suggestion or idea?

The best way to report these is also via the Feedback button on the DuckDuckGo.com search results page.

You can also share your thoughts with our community on Reddit.

duckduckhack-docs's Issues

Cheat Sheet Template Type

There seems to be more than four cheat sheet template types e.g. link but Documentation lists only four.

Is this intentional?

Document that places template group requires maps

The documentation omits to mention that in order for mapping functionality to work with the places template group the call to Spice.add() must be wrapped within a require block that imports maps, ie:

DDG.require(['maps'], function() { Spice.add( ...

http://docs.duckduckhack.com/frontend-reference/template-groups.html#places-template-group

Sign up walkthrough for Codio account is invalid

2a. Sign Up for a Codio Account

The steps mentioned are invalid now.

Solution

Sign up can be simplified by directly visiting Duckduckgo-Codio organisation signup link and then authorizing with github.

Error in image for Section 0.2

Noticed that the filepath for the HackerNews Perl file shows lib/DDG/Goodie/HackerNews.pm instead of lib/DDG/Spice/HackerNews.pm.

Settings 'Open In New Window' won't stick

I don't think I found the right 'Instant Answer' here ...

The subject line pretty explains it,
each time I come back to the internet, I have to reset that switch ...
How do I make it stay, I am signed in and
that cloud save, save settings, just don't seem to do shit ...

Use Templating

GitBook provides a templating system that allows us to specify re-usable variables and sections of markup to be used in multiple places.

I think this would be a good move - we have quite a lot of snippets that are repeated in multiple places throughout the docs; this would make it easier to update all of these at once, as well as reduce any typos copying up.

What's more, if we ever change which system we are using (GitBook, RTD, whatever), it should be relatively easy to move the snippets over.

Thoughts @talsraviv @moollaza?

Add remainder_lc to docs

@zachthompson mentioned this one, but I don't think it's in the docs (literally just lowercase version of remainder).

StyleGuide: Examples should start with good, end with bad

We should start the good vs bad examples (in the style guide) with good first, then bad. I've seen a few style guides use the suggested format and it reads better (IMO); as well as ensuring the readers see the good version first (first impressions guys)!

/cc @talsraviv

Document Cheat Sheet support for `\n` and `\t`

Cheat Sheets now support newlines and tabs (useful for code blocks).

• Any literal \n in the JSON will be converted to a <br> in the generated HTML
• Any literal \t in the JSON will be converted to    in the generated HTML

If you want to show a literal \n or \t in your JSON, you need to escape the slash: \\n or \\t

E.g. https://github.com/duckduckgo/zeroclickinfo-goodies/blob/master/share/goodie/cheat_sheets/json/common-escape-sequences.json#L48

Remove reference to 'simple' structured answers

There's some doc sections that make reference to the 'simple' structured answers:

Do we even support these still? AFAICT we are updating all previously 'simple' structured answers to use the new templates - which are more versatile and much more maintainable.

I would vote on removing reference to 'simple' structured answers - and focus on getting people using the full templates so that they know what's available, and have experience working with them which they can use when making more complex Instant Answers.

Maybe there is still a place for them - but I find it isn't much effort to just use a full template rather than the simplified version - and they are also a nightmare with tests!

What do you guys think? Encourage the use? Discourage the use? Wipe them completely?

/cc @talsraviv @moollaza @duckduckgo/community-leaders

Duckduckhack-docs: Make a calculation walkthrough displays the incorrect image

Issue: Make a calculation walk-through that shows the example for greatest common factor displays an image for bpm to ms goodie.

Steps for resolving the issue: Change the image link from wrong link
to
right link

People to notify:
@moollaza @pjhampton

Fix current examples provided on "Variants Reference" Page

Currently, many IA examples mentioned on the page don't work. One example is "electronics coupons" mentioned under detail variants.

reaching out to duckduckgo hacks

hey, so,
i searched for \u256D and was shown this:
it felt amazing, super nice.
thanks @mintsoft and @cosimo for making this

Add maintainership request template to Guidelines

Per chat w @GuiltyDolphin

Adding a template for maintainer Q/A when submitting a request to maintain an answer.

Add warning about renaming cloned repository

DuckPAN relies on the cloned repositories having the same name as the upstream repo (for ZCI, anyway) - we should add a warning not to rename the directory or DuckPAN may not work.

/cc @zachthompson

Tour Translation

Hey guys!

I recently wanted to "convince" (can you even say that? ;)) someone to use DDG, but i realized, that i could have been able to "convince" him a lot faster if the tour-page would have been in his language.. :J

So i was wondering if you could add the tour page to the list of translatable sites on duck.co, that'd be awesome! :D

Thanks and have a nice weekend!

Dead links

@talsraviv We've got quite a few dead links!

I've run a quick script I wrote on the .md files and it has turned up quite a few bad links. Some of them may be incorrect (a few sites that I've checked out), but many of them are pointing to Goodies or Spices.

I'll try and correct as many as I can, but there are some sections in the docs that talk about instant answers that no longer exist (I'll post with a full list ASAP).

"Tennis help" example no longer works

The intro page gives the example of "tennis help" as a search query that should "show a perfect result, above any ads or regular links". Only thing is the tennis cheat sheet IA isn't triggered by the work "help" any more. So the example doesn't do anything.

This seems to be because the IA is a cheat sheet of the type "reference" and only "guide"s are triggered by the word "help".

This is an issue but I'm not sure whether the solution is to update the documentation or to change the IA trigger. It seems better, to me, to change the IA to make this work again. But I don't know whether the change that broke this was on purpose or not.

Write walkthroughs for Programming Mission Fatheads

It would be nice to have a code walkthrough for each language that can be used for Fatheads.
A good selection of Fatheads to choose would be:

• jQuery
• Ruby
• MDN CSS

Codio link goes to trial period

In section 2b on this page the link to be added to the DDG organization on Codio doesn't go to a fully free page - it seems to go a trial page. Is there a new link we should use here?

(Reported via Twitter)

Document `links` template type for Cheat Sheets

@talsraviv we have another template type, links that look like the reference template but allows for a link property (instead of val) that's expected to be a URL.

This is used to create a cheat sheet made of clickable links. We currently use it for the NodeJS Tutorials Cheat Sheet: https://github.com/duckduckgo/zeroclickinfo-goodies/blob/master/share/goodie/cheat_sheets/json/nodejs-tutorials.json

Add more information on how FatHead articles are normalized

@moollaza Recently developed duckduckgo/p5-app-duckpan#358 - so we can now interact with FatHeads locally.

Unfortunately, things that look fine in local development do not look at all similar on Beta (missing text, malformed blocks etc.); this is likely due to additional processing done internally.

It would be useful to have some more information on what additional processing is done so we can better account for it when developing the FatHeads in the hope that what is presented on Beta is closer to what we see locally.

cc @moollaza @jdorweiler @jbarrett

pull-request: Avoid merge conflict

Terminology:
original repo - duckduckhack, forked repo - Dev repo (clone of duckduckhack) with Dev write access

The docs on how to submit a pull request does NOT give a hint (especially for noobs to Git) on adding a remote upstream link to original repo from which the Dev forks.

Currently, the process goes like this:

1. Setup Dev environment
2. Fork the original repo origin
3. Work locally, git commit and git push to forked repo origin
4. Submit a pull request

Problem: There could be new commits on original repo/branch in the meantime and it would result in conflicts if pull request from forked repo/branch is not updated/sync with original repo/branch. This might eventually fail pull request deployment to beta server.

Solution:

1. Setup Dev environment
2. Fork the original repo origin
3. Add a new git remote upstream to link original repo
4. Work locally, git commit and pull --rebase from upstream remote
5. Git push to forked repo origin
6. Submit a pull request

step 4 would sync forked repo/branch with original repo/branch and avoid merge conflicts on pull request (beta server deployment).

That said, there could be multiple ways of doing things with Git but this could be a useful guide for Dev.

I'd be glad to update the Docs if this issue has been validated by community leaders.

No mention of some meta properties

There is no mention of optional some meta properties like following in the docs:

• selectedItem
• scrollToSelectedItem

I'd like to add them to the docs, once someone confirms this.

@edgesince84 @moollaza @zekiel @talsraviv

Deprecate item_custom

duckduckgo/zeroclickinfo-spice#2356

Use POD documentation for Roles

backend-reference/goodie-helpers contains some documentation for the GoodieRoles.

Would it be possible to move this documentation over to POD, directly in the roles (as with WhatIs) then have some HTML generated for this (or other means) that the docs then use?

Would make it easier to keep the documentation in sync, as well as make it a lot easier for developers to view the documentation for the roles locally.

Outdated DNS Servers list

The instant answer for "DNS Servers": https://duckduckgo.com/?q=dns+servers&ia=answer
Shows multiple non-operating services, such as the "German Privacy Foundation", which makes it quite useless :/

Use Code Climate for linting

@talsraviv Code Climate just got a shiny, new, markdown linter, rules for which can be found here (there's a bunch!).

We could use this to enforce consistency across the docs, as well as detecting various errors! It is highly configurable (by the looks of it), so we could easily adapt it to suit our own particular preferences.

/cc @moollaza

tool bar button doesn't have focus

I love duckduckgo.
I recommend it to my friends and to my students.
I notice, though, that on the current release for Firefox [duckduckgo plus 1.1.19] on mac and windows both, when I click the toolbar button and the search window appears, I have to actually click in the duckduckgo search bar to give it focus before I can type in my search term. This is rather annoying, since in previous iterations the bar would have focus automatically, which seems like the natural way for it to operate.
Is there a setting I can configure that will give me that behavior? Or am I stuck forever with an extra click that I'll just have to get used to?
Thanks for your help, and for your wonderful product!

Typo Issue

There is typo error in documentation for the below page
https://docs.duckduckhack.com/programming-mission/creating-effective-fatheads.html#using-coverage-data-to-generate-redirects

Issue
cover/ mentioned as /cover

Update docs for recent DuckPAN change (allow IDs)

In duckduckgo/p5-app-duckpan#317 we added support for using IDs (and package names) in addition to the camel-cased name when using DuckPAN.

This means you can do things like duckpan test vim_cheat_sheet or duckpan query cheat_sheets; I think we should update the docs to reflect this; especially the section on testing cheat sheets.

/cc @talsraviv @zachthompson

`\n` `\t` not working?

Btw - was playing in codio - is this the right usage of \n? I didn't get a line break, and just ran duckpan upgrade before it

(didn't work for code template or keyboard template either)

Make it clear what aliases are for (cheat sheets)

I've been seeing a lot of cheat sheets with things such as X cheat sheet, X key bindings etc... in the aliases section - we need to make it clear that aliases are _strictly_ for alternative names - not triggers!

What do you think, @talsraviv?

Fathead Metadata field descriptions incomplete

On the Fathead Overview page (the section anchor link goes to the wrong page, so scroll to bottom), descriptions of the new metadata fields included on IA pages seems to be incomplete and contain an orphaned sentence at bottom.

Require additional information in Maintainer requests

Things such as "Why do you want to maintain this Instant Answer?", "What experience do you have that might help to improve this Instant Answer?" etc.

/cc @zekiel