embedly / embedly-docs Goto Github PK

Seems to be missing content under the Blog/cms plugins heading: http://wwwng.embed.ly/docs/authors

When you type embe, for example, no results are found, even though many results are found for embed. Users have been spoiled by Google to expect "fuzzy searching" so that they only have to type in approximate matches. Unfortunately, Searchify doesn't offer fuzzy search in and of itself. I may be able to partially remedy this by performing a combined search containing both what the user has actually entered and what the autocomplete API thinks they're trying to enter.

Alternatively, we may want to give the fresh-out-of-YC Swiftype a whirl... Searchify is just serving Indextank's product, not providing additional innovation.

http://wwwng.embed.ly/docs/endpoints/1/oembed does not have in page navigation on the left hand side, http://embed.ly/docs/endpoints/1/oembed does.

Again it helps with discovery.

Either have the nav floating as you scroll through the doc, probably to the right of the article, or insert "back to top" links after each section, so the user can get back to the article structure.

We should add some documentation on how to secure API requests via jsonp or xml-rpc calls. This is a combination of our referrers and ip whitelisting and oAuth.

We need to add keywords to each tutorial and doc so that they can be surfaced in a search.

Adding a list of key links to the left sidebar. Looks like this:

The list fades out when there's text in the search box, and fades back in when there isn't.

I've promised @screeley that embedly-docs will be open-sourced by the end of the week so I can move on to other projects. Before we do that, we need to ensure that the repo is free of sensitive information (passwords, API keys, etc.). I don't see why that information would be in embedly-docs in the first place, but it's worth considering.

It would also be nice for folks to have a version of the embedly-www server that they can run locally to preview their changes to the docs, like what you set up for me when I first signed on. That could be added as part of the repo. Doing it without including any sensitive information is the tricky part. We can't include the search indexing script, for instance.

Other thoughts?

There is a broken link at the bottom. I'm not sure if the intention was to merge this, but I would suggest a face lift and some re-org.

http://wwwng.embed.ly/docs/libraries

There are a lot of repeat tickets in our support system , that should be better surfaced in the Doc, Faq, and tutorials sections. Identifiy and start drafting copy.

description on this page: http://docs.embed.ly/docs/oembed#response-attributes should be optional. It's not returned for some objects. Ex: https://www.citizen.org/documents/GNEPFundingMay2006.pdf (Api Explorer)

some places it's JSON, others its json. same for URL/url

The developer entrance point should probably point to this page: http://embed.ly/docs/endpoints
vs. http://embed.ly/docs/tutorials/start

Also we should add a link to our libraries on the developers section of this page: http://wwwng.embed.ly/docs. , http://embed.ly/docs/libraries

This is an upstream bug that I don't think we should try to fix, but it's worth noting here: Any JSON containing a number with a decimal place currently breaks the Pygments syntax highlighting parser, causing the entire JSON snippet to go unhighlighted. See e.g. the example response from Foursquare at http://embed.ly/docs/endpoints/response#place

There is an open issue for this on the Pygments project, so cross your fingers and hope it gets fixed in the next release. (We're currently on the latest, 1.5.)

The first thing I want to do when I enter: http://wwwng.embed.ly/docs is click on authors or docs. It's bad that I cannot.

Search is good from finding something you already know, but we need to also cater to discovery.

Moved from https://github.com/embedly/doc-utils/issues/3:

We need to cater our entrance point to the docs for bloggers and developer separately.
i.e

Developers - should be presented with staring points to how to integrate the API itself and choose an API endpoint.
Bloggers - should be presented with how to install our Wordpress plugin, drop in a one line script tag into their existing blog platform, use Embedly Anywhere.

It does this in search, but it would be nice if they could be highlighted in the document itself. could be accomplished with a jquery plugin http://bit.ly/JVrNwC, but the term needs to be passed in to the doc

I am looking for IMDB integration, is it considered anytime?

Try entering d then quickly backspacing in the search box. You'll get a leftover d from the autocomplete. Clearly an async issue...