A TEMPLATE FOR TECHNICAL DESIGN DOCUMENTS TO HELP DISTRIBUTED SOFTWARE DEVELOPMENT TEAMS COLLABORATE BETTER
Abstract
Technical Design Documents (TDD) are commonly adopted documents in the software development industry that describe the technical solution implementation design. These documents are informal and lack strict requirements regarding their content. The structure often differs from organization to organization. Lack of standardized structure often results in low-quality design documents that can hinder successful technical solution implementation. In this paper, we applied a grounded theory method to analyze various organization-specific TDD structures and proposed a standardized structure for this document. In addition to the plain text structure, we visualized it in the form of a mindmap to facilitate the adoption of this template. Organizations can use the proposed TDD template structure as a basis for the company-specific structure of TDD and may include all or part of the sections proposed.
References
Aghajani, E., Nagy, C., Vega-Marquez, O. L., Linares-Vasquez, M., Moreno, L., Bavota, G., & Lanza, M. (2019). Software Documentation Issues Unveiled. 2019 IEEE/ACM 41st International Conference on Software Engineering (ICSE), 1199–1210. https://doi.org/10.1109/ICSE.2019.00122
Alwazae, M., Perjons, E., & Johannesson, P. (2015). Applying a Template for Best Practice Documentation. Procedia Computer Science, 72, 252–260. https://doi.org/10.1016/j.procs.2015.12.138
Bogolii, O. (2023). Agile Software Development in a Remotely Working Geographically Distributed Team: A Systematic Review. European Project Management Journal, 13(1): 23-36. DOI: 10.56889/idnv2224
Brown, S. (2018). The C4 Model for Software Architecture. InfoQ. https://www.infoq.com/articles/C4-architecture-model/
Caponi, A., Di Iorio, A., Vitali, F., Alberti, P., & Scatá, M. (2018). Exploiting patterns and templates for technical documentation (p. 9). https://doi.org/10.1145/3209280.3209537
Donovan, R. (2020, April 6). A practical guide to writing technical specs. Stack Overflow Blog. https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
Dupont, E. (2024, January 18). Create a functional and technical design document—Dynamics 365. https://learn.microsoft.com/en-us/dynamics365/guidance/patterns/create-functional-technical-design-document
Farrand, P., Hussain, F., & Hennessy, E. (2002). The efficacy of the “mind map” study technique. Medical Education, 36, 426–431. https://doi.org/10.1046/j.1365-2923.2002.01205.x
Golman, J. (2019, September 12). Design Docs at Google. Industrial Empathy. Retrieved from https://www.industrialempathy.com/posts/design-docs-at-google/
Henderson, C. (2024, March 21). Top 10 challenges documentation software solves. Paligo. https://paligo.net/blog/software/top-10-challenges-documentation-software-solves/
Jackson, S. E., Chuang, C.-H., Harden, E. E., & Jiang, Y. (2006). Toward Developing Human Resource Management Systems for Knowledge-Intensive Teamwork. In Research in Personnel and Human Resources Management (Vol. 25, pp. 27–70). Emerald (MCB UP ). https://doi.org/10.1016/S0742-7301(06)25002-3
Johannesson, P., & Perjons, E. (2014). An Introduction to Design Science. Springer International Publishing. https://doi.org/10.1007/978-3-319-10632-8
Kajko-Mattsson, M. (2008). Problems in Agile Trenches. In ESEM’08: Proceedings of the 2008 ACM-IEEE International Symposium on Empirical Software Engineering and Measurement (p. 119). https://doi.org/10.1145/1414004.1414025
Kalfat, H., Oussalah, M., & Chikh, A. (2023). ADM: An Agile Template for Requirements Documentation (p. 501). https://doi.org/10.5220/0012122400003538
Kingson, S. (2023). Guide to Create Technical Specification Document with Example. Document360. https://document360.com/blog/technical-specification-document/
LinkedIn community. (2023). What are the most common software project documentation challenges? Linkedin. https://www.linkedin.com/advice/1/what-most-common-software-project-documentation-oyqnc
Mage. (2021, September 14). How to Write Technical Design Docs. Dev.to. https://dev.to/mage_ai/how-to-write-technical-design-docs-c02
Nurlaila, A. P. (2013). THE USE OF MIND MAPPING TECHNIQUE IN WRITING DESCRIPTIVE TEXT. Journal of English and Education, 1(2), Article 2.
Orosz, G. (2018, October 03). Scaling Engineering Teams via RFCs: Writing Things Down. The Pragmatic Engineer. Retrieved July 24, 2023, from https://blog.pragmaticengineer.com/scaling-engineering-teams-via-writing-things-down-rfcs/
Seghiri, M., & Luque Giráldez, Á. (2023). Designing a technical specifications template in English a corpus-based approach (EN PRENSA).
Stanford University IT. (n.d.). Technical Design. Project Management | University IT. Retrieved June 24, 2023, from https://uit.stanford.edu/pmo/technical-design
Uikey, N., Suman, U., & Ramani, A. (2011). A Documented Approach in Agile Software Development. International Journal of Software Engineering, 2011–2013.
Wolfswinkel, J. F., Furtmueller, E., & Wilderom, C. P. M. (2013). Using grounded theory as a method for rigorously reviewing literature. European Journal of Information Systems, 22(1), 45–55. https://doi.org/10.1057/ejis.2011.51
This work is licensed under a Creative Commons Attribution 4.0 International License.
