Thanks very much Egon for your time, contribution and useful input!

@all - please take into account into your current and highly critical 
documentation work supporting involvement of an increasing number of 
developers, preparation for Rhodes development workshop etc. thx!

Barry

Am 16.08.2010 20:28, schrieb Egon Willighagen:
> 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
>
>