ШАБЛОН ДИЗАЙНУ ТЕХНІЧНОЇ ДОКУМЕНТАЦІЇ ДЛЯ КРАЩОЇ СПІВПРАЦІ РОЗРОБНИКІВ РОЗПОДІЛЕНИХ КОМАНД
Анотація
Документи технічного дизайну є загальноприйнятими документи в індустрії розробки програмного забезпечення, що описують дизайн імплементації технічного рішення. Ці документи є неформальними і не мають суворих вимог щодо їхнього змісту. Відсутність стандартизованої структури часто призводить до низької якості проєктних документів, що може стати на заваді успішної реалізації технічного рішення. Тому, корисною практикою є стандартизація структури документації технічного дизайну всередині організації, що сприяє налагодженню процесів розробки програмного забезпечення компанії. В цій статті ми використали метод обґрунтованої теорії, щоб проаналізувати структури документів, що використовуються в різних організаціях для опису технічного рішення. Після цього було застосовано осьове кодування для виявлення взаємозв'язків між категоріями та підкатегоріями в різних структурах документів, а також вибіркове кодування для інтеграції та уточнення визначених категорій. В результаті проведеного дослідження було представлено розроблений стандартизований шаблон документу технічного дизайну. Остаточна структура складається з 11 основних розділів: Вступ, Варіанти рішення, Подальші аспекти, Безпека та конфіденційність, Тестування, Імплементація, Впровадження та розгортання, Інструкції, Оцінка рішення, Відкриті питання та Наступні кроки. Вміст перелічених розділів описаний в основному тексті статті. Окрім звичайної текстової структури, ми візуалізували структуру у вигляді ментальної карти, щоб спростити її сприйняття. Запропонований шаблон був перевірений галузевими експертами та протестований на реальному проєкті. Загалом отримано позитивні відгуки. Організації можуть використовувати запропонований шаблон як основу для створення специфічних для компанії документів технічного дизайну, що можуть включати всі або частину запропонованих розділів.
Посилання
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
Ця робота ліцензується відповідно до Creative Commons Attribution 4.0 International License.
