Dear Juanjo, Concerning the format of Open Specifications proposed, our firm position on this matter is that several important modifications are indispensables. We strongly advocate that these modifications will considerably ease the task of providing Open Specifications for future and current APIs. The idea behind the recommendations and additional guidelines included here, is to account for the feedback from the developers, as well as keep track of their point of view. Experience has shown that verbose APIs specifications tend to be considered as hardly accessible from the users of a given API, who therefore prefer to simply discard the given API. This does not underestimate the crucial role of the documentation and specs of an API, but more precisely formulate the need for concision and efficiency in such documents. Our recommendations are as follow: - "Intended audience" can be reduced to a concise description, maybe the provided example is not intended to be taken verbatim, but this is only to give a definitive version. -"API Change History" may in some cases be useful for developers that use versioning, but the common practice (and a simpler one) is to provide these changes, showing the evolution of the API, at a separate notice, so that informed users may consult it if so required. - It is strongly recommended to define a unique set of instructions on "How to Read This Document" for all the APIs involved or developed in the project. This will be therefore located in a separate part of the repository containing all the APIs, so that redundancy, if not avoided, is at least kept at the lowest possible level. - The "Resources summary" as a diagram may be optional. We propose instead a simple listing in textual form of the nearest hierarchy, in the inheritance sense of the term. An example might be the beginning of each class' spec in the Java SDK. "Authentication", and "Representation Format" are to be filled according to the requirements of a given API (which may eventually include none). As for "Representation Format", since the indicated text on the Wiki must be included, and apparently is not subject to change, there is no obvious need to include it in each particular API, but in a separate section common to all the APIs. It is our firm belief that some of the fields mentioned in the proposal are superfluous, and do not answer to a precise need (such as "Resource identification"). Other fields are intuitively used where necessary, so explicitly listing them in the general form proposal may be avoided, and the choice left to the editor of the Open spec him(her)self (for ex. the "Optional" sections). The "Limits" section and subsections do not seem to offer a particular help in the task of informing users and the developers using the API. Maybe the advantage of having this should be provided? As examples to follow during the writing process of Open Specifications, and of our previous suggestions, the reader can refer to the JAVA API Specification (available at http://docs.oracle.com/javase/6/docs/api/ ), another example being the API Specifications provided by the Apache Foundation (such as Mojo, available at http://maven.apache.org/developers/mojo-api-specification.html ). These are of course only illustrations of what we are convinced to be very good examples of good practices to follow when providing the Open Specs, but remain nevertheless the blueprints of what to be expected as a result for an Open Specification. Best regards Daniel -------------- next part -------------- An HTML attachment was scrubbed... URL: <https://lists.fiware.org/private/old-fiware-security/attachments/20120406/0510b0c9/attachment.html>
You can get more information about our cookies and privacy policies clicking on the following links: Privacy policy Cookies policy