A domain independent readability metric for web service descriptions

Web Services are influencing most IT-based industries as the basic building block of business infrastructures. A Web Service has an interface described in a machine-processable format (specifically WSDL). Service providers expose their services by publishing the corresponding WSDL documents. Service consumers can learn about service capability and how to interact with the services. Service descriptions (WSDL documents) should be ideally understood easily by service stakeholders so that the process of consuming services is simplified. In this work we present a practical metric to quantify readability in WSDL documents – attending to their semantics by using WordNet as the underlying concept hierarchy. In addition, we propose a set of best practices to be used during the development of WSDL documents to improve their readability. To validate our proposals, we performed both qualitative and quantitative experiments. A controlled survey with a group of (human) service consumers showed that software engineers required less time and effort to analyze WSDL documents with higher readability values. Other experiment compares readability values of a dataset of real-life WSDL documents from the industry before and after modifying them to adhere to the readability best practices proposed in this paper. We detected a significant readability improvement for WSDL documents written according to the best practices. In another experiment, we applied existing readability metrics for natural language texts detecting their unsuitability to the Web Service context. Lastly, we analyzed the readability best practices identifying their useful applicability to the industry. •A practical metric to quantify readability in Web Services descriptions (WSDL).•A set of best practices to be used during the development of WSDL documents to improve their readability.•A controlled survey has been done to show the effort reduction of software engineers to analyze WSDL documents with high readability values.•Building documents following the best practices improve their readability values as we experienced with a dataset of real WSDL documents.