Creating Effective Reference Fatheads
While on the surface Fatheads appear simple, there are a few steps you can take toward increasing your Fathead's query coverage and accuracy.
This article will run through some of these, focusing on creating programming IAs.
Full topic coverage
A strong first step in planning your Fathead is to gather the set of articles you wish to provide coverage for.
If creating a programming Fathead, you need to create a
cover/ directory containing one or more text files (
.txt) that list all the topic titles and language features you need to cover (i.e. the specific keywords ). Using the example of a programming language Fathead, this list should come from a source separate to the Fathead source. For example, if using MDN you could use the list of reserved keywords from the ECMA specification.
These lists are used in two ways:
- As Unit tests to help measure your Fathead's coverage
- To generate extra article aliases (redirects) - see below
The Perl Fathead serves as a great example. It has two lists covering functions and special variables. The lists can be seen here.
Using Coverage Data To Generate Redirects
Special filenames can be used for the file(s) in your
/cover directory to automatically generate additional redirects (aliases) for your Fathead. The following filenames will generate redirects by prefixing, and appending the associated keywords to each article title in the file:
|methods.txt||method, function, func, subroutine|
|functions.txt||function, func, method, subroutine, keyword, call|
|variables.txt||var, variable, special variable|
|operators.txt||operator, function, func|
|tags.txt||tag, tags, element, elements, entity, entities, attribute, attributes|
|keywords.txt||function, func, method, class, object, obj, variable, var, keyword|
.add .addBack .addClass .after ...
- .add method, .add function, .add func, .add subroutine
- .addBack method, .addBack function, .addBack func, .addBack subroutine
- .addClass method, .addClass function, .addClass func, .addClass subroutine
- .after method, .after function, .after func, .after subroutine
Full coverage is great, but how do people then find your articles? The Fathead system is fast because it is simple - you need an exact match of the title in the search term.
- Article names with punctuation stripped and replaced by spaces (e.g. "array.length" would have an "array length" redirect)
- Camel case split into two lowercase words (e.g. "camelCase" would have a "camel case" redirect)
- Adding the reference category to the article title (e.g. "or" would become "or logical operator")
Try also thinking about what are the peculiarities of the language you're working on, and how people usually search for reference. For instance, in jQuery we have the following additional redirects:
- "on" + the event name ("on click")
- event name + "event" ("click event")
- $.[method] instead of jQuery.[method] ("$.ajax()")
Using a Redirects.txt file
Fatheads can use a
redirects.txt file to specify additional redirects for specific articles. This file can be generated from code, or manually compiled. Each line of the file should include the name of the redirect, and the name of the original article, separated with a comma.
::selection element, ::selection css pseudo element selection element, ::selection css pseudo element selection pseudo elements, ::selection css pseudo element css selection element, ::selection css pseudo element ambient lights, ambient light ambient lights api, ambient light api animated png, animated png (apng) animated pngs, animated png (apng) apngs, apng
|::selection element||::selection css pseudo element|
|selection element||::selection css pseudo element|
|selection pseudo elements||::selection css pseudo element|
|css selection element||::selection css pseudo element|
|ambient lights||ambient light|
|ambient lights api||ambient light api|
|animated png||animated png (apng)|
|animated pngs||animated png (apng)|
Future steps : Work is in progress on creating as many of these redirects automatically as possible, as well as feeding back common query misses to developers.
Specifying Trigger Words
Fatheads can use a
trigger_words.txt file to specify trigger words/phrases that are expected to appear before/after article titles in a query. Each line of the file should specify a unique word or phrase.
pyhton python python2 python2.6 python26 python2.7 python27 python 2 python 27 python 2.4 python 2.5 python 2.6 python 2.7 python 2.7.10 python 2.7.12
Given an article with a title of 'print', all of the following queries would now trigger the Python2 Instant Answer and show a result for the
- "pyhton print", "print pyhton"
- "python print", "print python"
- "python2 print", "print python2"
- "python2.6 print", "print python2.6"
- "python26 print", "print python26"
- "python2.7 print", "print python2.7"
- "python27 print", "print python27"
- "python 2 print", "print python 2"
- "python 27 print", "print python 27"
Any invalid entries in output.txt will be stripped from your Fathead on release. You should take steps to minimise invalid entries in output.
Common Errors :
- Field count
- Title duplication
- Disambiguation syntax
- Disambiguation titles not existing as articles
- Category titles clashing with article titles
To help you measure feature coverage and validity of your Fathead's output, a test exists to check for common issues and feature coverage. You can run this from the zeroclickinfo-fathead repository with DuckPAN like so:
duckpan test <your_fathead>
Alternatively, you can run:
DDG_TEST_FATHEAD=<your_fathead> prove -Ilib t/validate_fathead.t
your_fathead" is the name of your Fathead's directory in
lib/fathead/. This will provide detailed output on errors in your Fathead's
NB: Ensuring these tests pass is not a prerequisite for your Fathead to be merged. It is purely a helper to assist developers and reviewers to measure the potential effectiveness of their Fatheads.