Documenting Smart City Domain Requirements

The purpose of documentation is to instruct those who are unfamiliar with a system about how the system is structured, how it works, and the design rationale that led to it. In software development industry, the need for a well-designed documentation seems to be more important due to increasing complexity in the modern software.

History

As Selic (2009) stated, the software systems are typically revisited and revised more often, and the code maintenance is usually delegated to less experienced junior staff who are unfamiliar with the code. Documentation for smart services is of interest for two groups of stakeholders, i.e. authorities and service developers for the maintenance purpose. At the early time of emerging agile methods, the cons of these methods criticised that the emphasis on the code can result in corporate memory loss because there is little emphasis on producing good documentation to support complex systems (Turk et al., 2002). Bjarnason et al. (2011) expressed that one of the challenges experienced in applying the agile practice is getting the development teams to document the requirements. In a case study research, Moe et al. (2010) reported a rework on re-writing a whole module because of the absence of its first creator and because they have not understood how it was supposed to be used.

Examples

• lack of detailed documents is a challenge faced by the agile software development (Othmane et al., 2014; Gregory et al., 2016)

References

• Bjarnason, E., Wnuk, K. and Regnell, B., 2011, July. A case study on benefits and side-effects of agile practices in large-scale requirements engineering. In Proceedings of the 1st Workshop on Agile Requirements Engineering (p. 3). ACM.
• Gregory, P., Barroca, L., Sharp, H., Deshpande, A. and Taylor, K., 2016. The challenges that challenge: Engaging with agile practitioners’ concerns. Information and Software Technology, 77, pp.92-104.
• Moe, N.B., Dingsøyr, T. and Dybå, T., 2010. A teamwork model for understanding an agile team: A case study of a Scrum project. Information and Software Technology, 52(5), pp.480-491.
• Othmane, B.L., Angin, P., Weffers, H. and Bhargava, B., 2014. Extending the agile development process to develop acceptably secure software. IEEE Transactions on Dependable and Secure Computing, 11(6), pp.497-509.
• Selic, B., 2009. Agile documentation, anyone?. IEEE software, 26(6).
• Turk, D., France, R. and Rumpe, B., 2014. Limitations of agile software processes. arXiv preprint arXiv:1409.6600.