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.

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 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 Slide

3. crossOriginLoading
   DOCUMENTATION SEARCH
   Example camelCase parameter from webpack
   

   View 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 Slide

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

   View 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 Slide

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

   View 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 Slide

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

   View Slide

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

    View Slide

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

    View 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 Slide

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

    View Slide

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

    View 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 Slide

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

    View Slide

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

    View 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 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 Slide

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

    View Slide

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

    View Slide

22. Learn more @ blog.algolia.com
    

    View Slide

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

    View Slide