Upgrade to Pro — share decks privately, control downloads, hide ads and more …

7 ways to search for a camelCased parameter in your docs

Josh Dzielak
December 13, 2016

7 ways to search for a camelCased parameter in your docs

Technical documentation contains word patterns like camelCase that give traditional search engines a headache. See how Algolia makes camelCase parameters searchable by 7 different types of queries. Given at API Days Paris 2016.

Josh Dzielak

December 13, 2016
Tweet

More Decks by Josh Dzielak

Other Decks in Technology

Transcript

  1. December 13th, 2016
    7 ways to search for a
    camelCased parameter
    in your docs
    Josh Dzielak // @dzello
    Developer Advocate @algolia
    APIDays Paris

    View full-size slide

  2. https://www.dropbox.com/s/ipty10vd9c7u4jv/Screenshot%202016-12-13%2012.01.04.png?d
    l=0
    DOCUMENTATION SEARCH
    Do your docs have a search?
    Search the docs...
    Get community.algolia.com/DocSearch, used by:

    View full-size slide

  3. crossOriginLoading
    DOCUMENTATION SEARCH
    Example camelCase parameter from webpack

    View full-size slide

  4. DOCUMENTATION SEARCH
    7 common queries for this parameter
    1. `crossOriginLoading`
    2. `cross Origin Loading`
    3. `Origin`
    4. `OriginLoading`
    5. `Origin cross`
    6. `Origin Loading`
    7. `OriginLoad`
    Note: all uppercase/lowercase characters are treated the same

    View full-size slide

  5. DOCUMENTATION SEARCH
    camelCased Query #1 (original name)
    crossOriginLoading|
    OK! \o/
    User remembered the name perfectly.
    No typos. User gets a CAMEL!

    View full-size slide

  6. DOCUMENTATION SEARCH
    camelCased Query #2 (split name)
    cross Origin Loading|
    OK! \o/
    Search engine concatenates query
    to match `crossOriginLoading`
    User keeps their CAMEL!

    View full-size slide

  7. DOCUMENTATION SEARCH
    camelCased Query #3 (middle word only)
    Origin|
    NO RESULTS /o\
    `Origin` does not match
    `crossOriginLoading`

    View full-size slide

  8. DOCUMENTATION SEARCH
    Fix #1: Uncamelizing
    Split word into parts by capital letter
    `crossOriginLoading` =>
    `cross Origin Loading`
    Caution: Don’t split “API” into “A P I”

    View full-size slide

  9. DOCUMENTATION SEARCH
    camelCased Query #3 (middle word only)
    Origin|
    FIXED! \o/
    `origin` is a 1-word match with
    `cross Origin Loading`

    View full-size slide

  10. DOCUMENTATION SEARCH
    camelCased Query #4 (later words)
    Origin Loading|
    OK! \o/
    `Origin Loading` is 2-word match of
    `cross Origin Loading`

    View full-size slide

  11. DOCUMENTATION SEARCH
    camelCased Query #5 (words reversed)
    OK! \o/
    `Origin cross` will 2-word match
    `cross Origin Loading`
    Origin cross|

    View full-size slide

  12. DOCUMENTATION SEARCH
    camelCased Query #6 (later words)
    OriginLoading|
    MOSTLY OK!
    `OriginLoading` is a 1-typo match for
    `Origin Loading`
    1 typo: it will appear in results but potentially lower ranking.

    View full-size slide

  13. DOCUMENTATION SEARCH
    Back to camelCased Query #1
    crossOriginLoading|
    WAS BROKEN BY WORD SPLITTING /o\
    Can no longer search by parameter name

    View full-size slide

  14. DOCUMENTATION SEARCH
    Fix #2: Synonyms
    Add 1-way synonym from:
    `crossOriginLoading`
    to
    `cross Origin Loading`

    View full-size slide

  15. DOCUMENTATION SEARCH
    Back to camelCased Query #1
    crossOriginLoading|
    FIXED! \o/
    Synonym matches `cross Origin Loading`
    Results show `crossOriginLoading` w/ no spaces, spaces
    are replaced by invisible unicode character \u2063

    View full-size slide

  16. DOCUMENTATION SEARCH
    camelCased Query #7 (later term partial)
    OriginLoad|
    NO RESULTS /o\
    `OriginLoad` will not match
    `Origin Loading`

    View full-size slide

  17. DOCUMENTATION SEARCH
    Fix #3: More Synonyms
    Add 1-way synonym from:
    `OriginLoading`
    to
    `Origin Loading`

    View full-size slide

  18. DOCUMENTATION SEARCH
    camelCased Query #7 (later term partial)
    OriginLoad|
    FIXED! \o/
    `OriginLoad` will prefix-match synonym
    `OriginLoading` thereby becoming
    `Origin Loading` and a 2-word match of
    `cross Origin Loading`

    View full-size slide

  19. DOCUMENTATION SEARCH
    Recap: 7 common camelCase queries
    1. `crossOriginLoading`
    2. `cross Origin Loading`
    3. `Origin`
    4. `OriginLoading`
    5. `Origin cross`
    6. `Origin Loading`
    7. `OriginLoad`

    View full-size slide

  20. DOCUMENTATION SEARCH
    See DocSearch in action
    on the upcoming webpack docs
    http://webpack.js.org

    View full-size slide

  21. SPECIAL MENTION
    Help sustain open source!
    Visit opencollective.com
    webpack

    View full-size slide

  22. Learn more @ blog.algolia.com

    View full-size slide

  23. December 13th, 2016
    Thanks!
    Josh Dzielak // @dzello
    Developer Advocate @algolia

    View full-size slide