Hi Egon,

Many thanks for the review. Obviously, addressing all the comments
will require lot of work !

Regarding the ontology visualisation I find this very useful (probably
because it reminds JavaDoc page)

http://www.mygrid.org.uk/OWL/Presentation?url=http%3A%2F%2Fopentox.org%2Fapi%2F1.1%2Fopentox.owl

Best regards,
Nina

On Mon, Aug 16, 2010 at 9:28 PM, Egon Willighagen
<egon.willighagen at gmail.com> wrote:
> 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
> _______________________________________________
> Development mailing list
> Development at opentox.org
> http://www.opentox.org/mailman/listinfo/development
>