API Documentation Improvments

[aoifespenge]

Summary

We got feedback from a user that indicates a few ways the API Docs need to be improved. I'm outlining here the main areas that can be improved:

• The user needs an explanation of what to expect with the search results. They need the JSON search results structure to be outlined, i.e. The results will be research publication and nested within it any policy documents that cited it.
• They need to know that the input search term will run through all the possible fields in the research publication and the associated policy doc, and will always return results where that term is in any of those fields.
• They need to understand that the search logic is an OR logic, not an AND.
• The list of searchable fields needs to be comprehensive. At the moment the list include only some of the searchable fields, e.g. it doesn't mention DOI.
• Error feedback: When a search results fail the user needs to know whether this was because 1)user error; 2) system error; 3) the was nothing found based on the data we have.
• The user needs to know that they cannot search for more than one research publication at once. If there is a programmatic solution to this, the documentation should explain how to do this, i.e. creating a piece of code that you can input but will loop over a multiple publications.

Motivation

The API documentation needs to be self-explanatory. These simple changes will move the docs to being understandable by someone outside the team who doesn't have our knowledge of the tool.

Proposal

As Sam was presented at the session with the user, I would recommend he make the changes to the documentation based on the above bullet points and from what was discussed.

It's worth walking through it again once done, so once the changes are done if he can let me and Dawn know and we will contact the user to run through.

.

[aoifespenge]

I think the API document should also clearly state the accurate product offering, which is along the lines of: "We can find where scientific publication that are in the EPMC database are cited in policy documents, but only from X policy sources and only if we have a reference section. "

[aoifespenge]

@SamDepardieu @dd207 will this ticket be added to a sprint backlog this quarter? Would be better to make these changes before going to another Reach user to do a diary study