[OTDev] Superservice section of API documentation
Roman Affentranger roman at douglasconnect.comMon Jan 31 13:45:19 CET 2011
- Previous message: [OTDev] A&A: Policy cleanup
- Next message: [OTDev] Superservice section of API documentation
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
Dear Christoph Few comments regarding the superservice documentation. 1) "Super service" is a part of "5. Algorithm Types", but the title has a different color than the other algorithm types. 2) Under the REST operations, there are links for Parameters, Result and Status Codes for GET ("as in Algorithm"). These links point to opentox.org/dev/Algorithm, which doesn't exist... 3) I find the "introduction" sentence a bit confusing: ===== Super Service Allows to create models and specify descriptor calculation , feature selection and possibly other services, necessary to generate the data, required by the model building algorithm A superservice for creating models is a specific instance of an algorithm, with input parameters defined below. The result of a super algorithm is a super model (see Model API). ===== I think this could be a bit more clear, e.g. ===== Superservice A Superservice is a specific instance of an algorithm that, like a regular algorithm, creates a model, but additionally allows for specific definition of the individual services (descriptor calculation, feature selection, and possibly other services) necessary to generate the data required by the model building algorithm. The result of a Superservice is a Supermodel (see Model API) ===== I don't know if the above sentences are even correct, but I think something like that would be more clear. In particular: - If you say "a superservice for creating models is a specific instance of an algorithm", this gives the impression that there are Superservices wih another purpose than creating models. Is that true? If so, it could be made more clear. If not, I'd suggest rephrasing as I suggested above. - The last sentence "The result of a super algorithm is a super model (see Model API)" should be rephrased. The term "super algorithm" appears out of nowhere. What's the difference between a Superservice and a Superalgorithm? - "(see Model API)" should be a link to the Model API. So, overall, I think it is fairly clear, however, could be made more clear ;) In particular, the terminology should be revisited (Superservice vs Superalgorithm. If both, both need to be defined). Also, the spelling should be unified (Super Service, super service, Superservice, etc.). That is: one word, two words? Capital letters/lower-case letters? Same for Supermodel, Superalgorithm (if we keep it). Since it clearly states that the output of a Superservice/Superalgorithm is a Supermodel, I'll look at that next.... Best regards, Roman
- Previous message: [OTDev] A&A: Policy cleanup
- Next message: [OTDev] Superservice section of API documentation
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
More information about the Development mailing list