Hi Barry,

please find below my comments, which are brief, and please do not
hesitate to ask me to clarify things where needed.

On Sat, Jul 17, 2010 at 7:33 PM, Barry Hardy
<barry.hardy at douglasconnect.com> wrote:
> Would you consider reviewing the current OpenTox API documentation located
> at http://www.opentox.org/dev/apis and providing some feedback?

OpenTox API 1.1 Documentation Review

Pages reviewed are prefixed with ****. At the end I'll summarize things.

**** http://www.opentox.org/dev/apis

- Title "API" written in full, perhaps add OpenTox and version number.

**** http://www.opentox.org/dev/apis/api-1.1

- The page does not have a short introduction on how to navigate the
page and somewhat overwhelming.
- The 'Common specifications for all APIs' section should refer to
HTTP as second important underlying API
- The 'parameters' section mixes specification with examples... I
suggest putting the 'curl -d' talk under the 'Example' header
- "but service developers may support additional formats. You can
request them," -> 'them' unintentionally refers here to those
additional formats, but refers to how to use them instead.
- inconsistent header level for 'Example'
- I would suggest separating specification and example completely, and
cross link between them instead
- add a link for the RDF/XML format with further details
- I'd also suggest to make something like a separate 'Common' page,
and have this page give an overview

**** http://www.opentox.org/dev/apis/api-1.1/OpentToxResources/view

- 'Overview' suggests more than just a screenshot of the OWL model
rename this page to 'Data Model' or so
- I also suggest to use an OWL HTML viewer to make the OWL web browsable
- All further pages should refer to this ontology, such as:
http://www.opentox.org/dev/apis/api-1.1/structure should point to the
Compound OWL definition

**** http://www.opentox.org/dev/apis/api-1.1/structure

- the table with tasks should include a column with at least one
example, preferably live and clickable, URL
- the status code numbers should be clickable and point to HTTP documentation
- the GET, POST keywords should be clickable and point to HTTP documentation
- the page lacks a TOC, so it is not really clear that there is a
/conformers/ section hidden down the bottom
- Compound (all all other classes) are not described, for which you
could like to the OWL

**** http://www.opentox.org/dev/apis/api-1.1/Feature

- typo: Decsriptor
- the page links in the intro to a few ontologies... those should be linked to

**** Overall

- The comments about most other pages are the like those given for
/structure... overall, the documentation is difficult to navigate.
- add the missing overview: guide the reader to the right part of the API
tables with various API calls should be restructured:
- soft by method, not by task: first column should say /model
- list paramaters in different rows, and describe each of them. I now
have to guess from the given task
- add links to further material... e.g. the HTTP return codes are not
visible linked to the matching table, which is easily overlooked
- the API is also very much a mix of use cases and specification;
instead, I suggest to
- write one formal specification, much like JavaDoc
- write a primer (using curl) how a particular workflow may look like,
composed of the tasks - now in the documentation
- better use of headers, to show how important the various parts are
- integrate the OWL backing up much of the API, and make it browsable
via the web, e.g. using http://ontologyonline.org/

I hope you find these comments useful.

Greetings,

Egon

-- 
Dr E.L. Willighagen
Post-doc @ Uppsala University (only until 2010-09-30)
Proteochemometrics / Bioclipse Group of Prof. Jarl Wikberg
Homepage: http://egonw.github.com/
Blog: http://chem-bla-ics.blogspot.com/
PubList: http://www.citeulike.org/user/egonw/tag/papers