ABSTRACT
Understanding an unfamiliar program is always a daunting task for any programmer, either experienced or inexperienced. Many studies have shown that even an experienced programmer who is already familiar with the code may still need to rediscover the code frequently during software maintenance. The difficulties of program comprehension is much more intense when a system is completely new. One well-known solution to this notorious problem is to create effective technical documentation to make up for the lack of knowledge.
The purpose of technical documentation is to achieve the transfer of knowledge. However, creating effective technical documentation has been impeded by many problems in practice [1]. In this paper, we propose a novel tool called GeekyNote to address the major challenges in technical documentation. The key ideas GeekyNote proposes are: (1) documents are annotated to versioned source code transparently; (2) formal textual writings are discouraged and screencasts (or other forms of documents) are encouraged; (3) the up-to-dateness between documents and code can be detected, measured, and managed; (4) the documentation that works like a debugging-trace is supported; (5) couplings can be easily created and managed for future maintenance needs; (6) how good a system is documented can be measured. A demo video can be accessed at https://youtu.be/cBueuPVDgWM.
- Emad Aghajani, Csaba Nagy, Olga Lucero Vega-Márquez, Mario Linares-Vásquez, Laura Moreno, Gabriele Bavota, and Michele Lanza. 2019. Software documentation issues unveiled. In Proceedings of the 41st International Conference on Software Engineering, ICSE 2019, Montreal, QC, Canada, May 25-31, 2019, Gunter Mussbacher, Joanne M. Atlee, and Tevfik Bultan (Eds.). IEEE / ACM, 1199--1210. https://dl.acm.org/citation.cfm?id=3339655Google ScholarDigital Library
- Yung-Pin Cheng, Jhih-Hao Chen, and Yu-Ying Yu. 2013. Executable Program Documentation Based on Debugging Break Points. In 20th Asia-Pacific Software Engineering Conference, APSEC 2013, Ratchathewi, Bangkok, Thailand, December 2-5, 2013 - Volume 1. IEEE, 199--206. Google ScholarDigital Library
- Andrew Forward and Timothy Lethbridge. 2002. The relevance of software documentation, tools and technologies: a survey. In Proceedings of the 2002 ACM Symposium on Document Engineering, McLean, Virginia, USA, November 8-9, 2002. ACM, 26--33. Google ScholarDigital Library
- InfoQ. 2019. How do you document your APIs. Available as https://www.infoq.com/research/api-documentation/.Google Scholar
- IsCoollab. 2018. KORAT - a Human-Computer Interaction Robot. Available as https://iscoollab.com.Google Scholar
- Mira Kajko-Mattsson. 2005. A Survey of Documentation Practice within Corrective Maintenance. Empirical Software Engineering 10, 1 (2005), 31--55. http://www.springerlink.com/index/10.1023/B:LIDA.0000048322.42751.caGoogle ScholarDigital Library
- N. Pennington. 1987. Stimulus structures and mental representations in expert comprehension of computer programs. Cognitive Psychology 19 (1987), 295--341.Google ScholarCross Ref
- Pablo Romero, Benedict du Boulay, Richard Cox, Rudi Lutz, and Sallyann Bryant. 2007. Debugging strategies and tactics in a multi-representation software environment. International Journal of Man-Machine Studies 65, 12 (2007), 992--1009. Google ScholarDigital Library
- Christoph Johann Stettina and Werner Heijstek. 2011. Necessary and neglected?: an empirical study of internal documentation in agile software development teams. In Proceedings of the 29th ACM international conference on Design of communication, Pisa, Italy, October 3-5, 2011, Aristidis Protopsaltis, Nicolas Spyratos, Carlos J. Costa, and Carlo Meghini (Eds.). ACM, 159--166. Google ScholarDigital Library
- Junji Zhi, Vahid Garousi-Yusifoglu, Bo Sun, Golara Garousi, S. M. Shahnewaz, and Günther Ruhe. 2015. Cost, benefits and quality of software development documentation: A systematic mapping. Journal of Systems and Software 99 (2015), 175--198. Google ScholarDigital Library
Index Terms
- GeekyNote: a technical documentation tool with coverage, backtracking, traces, and couplings
Recommendations
Technical documentation and related contractual liability
SIGDOC '99: Proceedings of the 17th annual international conference on Computer documentationThis paper examines major issues of liability that the Technical Writer faces in preparing documentation for the End User. The three relationships present in creation and delivery of documentation are defined, as well as the relationships between ...
Documentation threads - presentation of fragmented documentation
In this paper, we introduce a means for presenting fragmented documentation through a concept called documentation threads. A documentation thread presents a number of documentation fragments specified by the programmer and can guide a documentation ...
Executable Program Documentation Based on Debugging Break Points
APSEC '13: Proceedings of the 2013 20th Asia-Pacific Software Engineering Conference (APSEC) - Volume 01Understanding an unfamiliar program is always a daunting task for any programmer, either experienced or inexperienced. Many studies have shown that even an experienced programmer who is already familiar with the code may still need to rediscover the ...
Comments