Documentation Practices in Agile Software

Development: A Systematic Literature Review

Md Athikul Islam Rizbanul Hasan Nasir U. Eisty
Department of Computer Science Department of Computer Science Department of Computer Science
Boise State University Boise State University Boise State University
Boise, ID, USA Boise, ID, USA Boise, ID, USA
[email protected] [email protected] [email protected]
arXiv:2304.07482v1 [cs.SE] 15 Apr 2023

Abstract—Context: Agile development methodologies in the and customer involvement. Over the past decade, numerous
software industry have increased significantly over the past software developers have adopted the ASD model [33]. This
decade. Although one of the main aspects of agile software concept of agile is gained by different agile methodologies like
development (ASD) is less documentation, there have always been
conflicting opinions about what to document in ASD. Objective: Scrum, eXtreme Programming (XP), Crystal, Lean, Dynamic
This study aims to systematically identify what to document Systems Development Method (DSDM), and Feature-Driven
in ASD, which documentation tools and methods are in use, Development (FDD). Documentation has a lower priority
and how those tools can overcome documentation challenges. than working software in Agile practices [27]. Some agile
Method: We performed a systematic literature review of the practitioners consider code as its documentation. As a result,
studies published between 2010 and June 2021 that discusses
agile documentation. Then, we systematically selected a pool the information that is recorded in documentation (documented
of 74 studies using particular inclusion and exclusion criteria. information, henceforth) may not be well maintained, result-
After that, we conducted a quantitative and qualitative analysis ing in inadequate information for the team to understand
using the data extracted from these studies. Results: We found development tasks [40]. Another reason for less focus on
nine primary vital factors to add to agile documentation from documentation is that it consumes time that could have been
our pool of studies. Our analysis shows that agile practitioners
have primarily developed their documentation tools and methods allocated in development [70].
focusing on these factors. The results suggest that the tools and As modern software systems are complicated, developers
techniques in agile documentation are not in sync, and they revisit the system more often. Trivial maintenance work is
separately solve different challenges. Conclusions: Based on our assigned to junior developers who have little experience with
results and discussion, researchers and practitioners will better the code. As a result, lack of documentation hinders inter-
understand how current agile documentation tools and practices
perform. In addition, investigation of the synchronization of these team building and knowledge loss [78]. In addition, users of a
tools will be helpful in future research and development. software product expect quality results [2]. Considering these
Index Terms—Software Engineering; Agile Software Develop- scenarios, agile documentation plays a significant role in ASD
ment; Documentation; Systematic Literature Review [70], [71]. Moreover, offshore agile development is widespread
nowadays, and documentation is one of the key factors to
I. I NTRODUCTION make offshore agile development successful [58]. Therefore,
Software documentation is an integral part of software developers should document the features of each iteration to
development. It works as a communication medium between help future developers refactor them into smaller tasks.
developers of a team and is utilized as an information reposi- The practitioners working on agile documentation have
tory by maintenance engineers [76]. Documentation elucidates implemented different documentation strategies to overcome
how the system is structured, its functionalities, and the design the issues raised by the lack of documentation. They have
rationale [70]. Software documentation should be included as identified different key elements that developers should doc-
part of software development and is sometimes called “com- ument such as user stories, functional requirements, source
mon sense” [26]. Even outdated document serves a purpose code, etc [10], [13], [43]. They have also developed various
and may be helpful [26]. However, the incomplete, wrong, tools and models such as wikis, simul loco, doxygen, etc to
clumsy, abstruse, outdated, and inadequate document often document these elements effectively [9], [55], [66]. In this
leads to the unpopularity of software documentation among the paper, we focus on understanding the pivotal information to
developers [4]. Regardless of the application type, almost all document in agile and the existing techniques and tools that
medium to large software projects produces a certain amount result in document optimization. We conducted a systematic
of documentation [76]. literature review from existing research and analyzed them to
ASD is an iterative approach that helps teams deliver answer our research questions mentioned in section II. Our
value to their customers faster and more efficiently. It is findings will benefit any agile practitioners and developers to
immensely applied in both industry and academia [54]. This optimize their documentation effort and help researchers in
incremental approach maintains a strong focus on project goals further study.
II. R ESEARCH M ETHODOLOGY TABLE I
S EARCH STRING
In our research methodology, we followed the directions
proposed by Kitchenham and Charters [45]. We have divided
Search string
our research review into four steps, namely planning, conduct-
ing, and reporting the review results. ((("Document Title": "agile" OR "Abstract": "agile")
AND ("Document Title": "document*" OR "Abstract":
A. Planning
"document*")) OR ("Document Title": "document*
We have planned this review by confirming the need for tools" OR "Abstract": "document* tools"))
such a review and have proposed our research questions ac-
cordingly. Our planning phase includes search strategy, search
string, and inclusion/exclusion criteria.
1) Research questions: We pose the following research conferences and journals, and published within the time frame
questions to drive this study. 2010 - 2021. The published papers should describe the agile
documentation approach, tools, or knowledge relevant to our
• RQ1: Which information do agile practitioners doc-
RQs. Therefore, we did not include any opinion, viewpoint,
ument?
keynote, discussions, editorials, comments, tutorials, prefaces,
• RQ2: Which documentation generation tools and
anecdote papers, and presentations. In addition, we excluded
methods do agile practitioners use?
the papers that did not discuss agile documentation or agile
• RQ3: How can the tools and methods overcome the
documentation tools but may discuss agile software develop-
documentation challenges in agile software develop-
ment methods as a side topic.
ment?
2) Search strategy: After defining the need for this sys- B. Conducting the review
tematic review and research questions, we started to carry Once we agreed on the protocol, we started our review
out the formulation of a search strategy based on the guide- properly. This section discusses the findings of our search and
lines provided by Kitchenham and Charters [45]. In Table extracted data from relevant databases and sources.
I we broke down the question into individual facets i.e. 1) Study search and selection: We searched the IEEE
population, intervention, and constructed search string using Xplore database against our search query and search criteria
Boolean ANDs and ORs. We initially fetched studies from the and fetched 206 studies. In round 1, the first author immensely
electronic databases and then explored them through reference analyzed the titles and abstracts of the fetched studies based
searches (snowballing) to seek other meaningful studies. After on the inclusion criteria. After the first round, we came out
that, we applied our inclusion and exclusion criteria to the with 77 papers, and most of these studies covered all the
fetched studies involving a different number of researchers, as inclusion criteria. A critical part was to ensure the papers did
explained in Section II-A4. not come from opinions, discussions, editorials, comments,
3) Search criteria: The search criteria used for this review tutorials, prefaces, and presentations as per the exclusion
consist of three parts - C1, C2, and C3, defined as follows: criteria. In round 2, we inspected the full-text review of the
• C1: We constructed the C1 string, which enables the papers based on all inclusion and exclusion criteria. We read
keyword agile either in the title or abstract. the papers fully a few times where there were disagreements
• C2: The C2 string is made up of keywords such as and required consensus. We excluded 23 papers based on the
document or document* either in title or abstract. exclusion criteria. Finally, to satisfy the inclusion of relevant
• C3: We constructed the C3 part, which enables keywords primary studies as much as possible, we performed backward
such as tools or document* tools either in the title or and forward snowballing following the guideline provided by
abstract. Wohlin [84] and included 20 more papers in our list of primary
The boolean expression: C1 AND C2 OR C3 studies. The final pool of selected papers was 77.
We provided our search string in Table I. 2) Data extraction: We followed the data extraction strat-
Another key thing to note is that we have filtered out the egy of Kitchenham and Charters [45] and came up with a data
result fetched from the search query by applying the checkbox extraction form that we designed to collect all the information
feature of the IEEE Xplore database. In this case, we filtered needed to address the review questions. We set a few quality
out publication topics such as internet, organizational aspects, evaluation criteria, such as
computer-aided instruction, DP industry, computer science ed- • How well was data collection carried out?
ucation, educational courses, knowledge management, mobile • Is the research design defensible?
computing, security of data, business data processing, and • How much are the findings credible?
teaching not relevant to our research. • Is the research scope well addressed?
4) Inclusion and exclusion criteria: As per the guidelines In addition to the RQs and quality evaluation criteria, the
of Kitchenham and Charters [45] we have set inclusion and form included the data as (i) name of the reviewer, (ii) date
exclusion criteria based on our research questions. Here, we of data extraction, (iii) title, (iv) authors, (v) journal, (vi)
only considered papers that are in English, published in publication details, (vii) future work, (viii) limitations, (ix)
year of publication, (x) methodology, (xi) data analysis, (xii) 7) System architecture: Some documentation tools have
validation technique, (xiii) relevancy and xiv) space for addi- evolved to document architecture [10], [31]. Architecture
tional notes. This data extraction was performed independently works as the backbone of the entire system [10]. Documenting
by the first and second authors. architecture is one of the most complicated and challenging
3) Data synthesis: After the data extraction, we combined parts of software development [31].
and summarized the results of the included primary studies 8) API reference guides: To understand the usage and
according to the guidelines of Kitchenham and Charters [45]. integration of API, APIs should have comprehensive docu-
Our data synthesis includes both quantitative and descriptive. mentation. Good API reference guides make the APIs easier to
For the descriptive synthesis, we tabulated the data based on maintain and helps onboard new developers to the team [75].
research questions. In this case, we synthesized what type of 9) Test specification: It is tough to demonstrate large-scale
information and tools are used in agile documentation. On systems solely using test cases in the industry. Testing needs
the other hand for quantitative synthesis, we again developed more mature documentation to keep track of the test cases,
a tabular form for research questions. These tables were user scenarios, and bugs [10].
structured to highlight similarities and differences between
study outcomes. Later the data of these tables were represented B. (RQ2) Which documentation generation tools and meth-
by bar charts and pie charts. ods do agile practitioners use?
In order to answer this research question, we first explored
III. R ESULTS the current tools and methods used in ASD from our primary
In this section, we present our findings. We address each pool of studies and found a total of 23 tools and methods.
research question from RQ1 to RQ3. Next, we categorized them based on their document type and
found ten categories. Table III lists categories alongside their
A. (RQ1) Which information do agile practitioners docu- tools and Figure 1 shows the percentage of tools under each
ment? category. We also listed the studies that reported the tools and
methods. Moreover, we mentioned the role of each tool or
Table II summarizes our findings of documented informa- method in the right-most column of the table.
tion. Our primary pool of studies consisted of interviews, sur-
veys, case studies, experiments, and statistical analysis. Many
agile practitioners, graduate students, and software engineers
directly participated in these studies. We collected the findings
from these studies and grouped them. The following sections
briefly describe each element of Table II.
1) User stories: User stories function as the shortcut for
more formal documentation and require more details [29]. On
the other hand, they represent the small, concise user-driven
features and hence need to be documented [56].
2) Functional requirements: End-users define these re-
quirements and expect them as facilities when they interact
with the system. Therefore, these functionalities focus more
on the technical aspects that need to be implemented [57].
3) Non-functional requirements: The success of an agile Fig. 1. Categorisation of documentation tools/methods
project depends on the non-functional requirements, which
are also referred to as quality requirements [12]. These re- 1) Source code based documentation: Source code-based
quirements are quality constraints that must be satisfied by the documentation can mitigate certain risks [32]. This category
system. So, failure to meet these requirements compromises consists of 6 tools, and these tools mainly focus on how
the entire system and makes it useless [23]. software practitioners can generate documentation from source
4) Source code: The source code should be documented for code comments. These tools cover the functionalities of some
traceability and deriving the code that does not perform [10]. of the popular documentation generation tools like JavaDoc or
5) UI structure: These are wireframes and sometimes are Docstring and offer some additional features [44].
documented externally. However, they can be the basic layouts 2) Wiki based documentation: When developers consider
of application screens and the product owner usually provides straightforward and flexible documentation options in agile,
these wireframes [13]. they consider wiki-based documentation in the first place
6) Technical debt: If a system needs fixes or updates, it because the primary goal of the wiki is to minimize the devel-
is best to document them currently. Similarly, it is best to opment–documentation gap by making documentation more
document them in the case of technical debt. As a result, future convenient and attractive to developers [80]. For example,
developers will be aware of that technical debt. Therefore, all sprintDoc and XSDoc are tools based on wikis and can be
instances of technical debt should be documented [36]. integrated with other tools such as the VCS IDE.
TABLE II
K EY ELEMENTS TO ADD IN AGILE SOFTWARE DOCUMENTATION

No. Information to document Studies that reported the information

1 User stories [10], [13], [20], [28], [30], [34], [37], [56], [57], [65], [78], [82]
2 Functional requirements [10], [31], [57], [65], [71]
3 Non-functional requirements [10], [12], [13], [23], [37], [47], [81]
4 Source code [10], [43], [44], [55], [66], [83]
5 UI structure [13], [34], [37], [57], [78]
6 Technical debt [12]
7 System architecture [10], [28], [31], [78]
8 API reference guides [38], [57], [75]
9 Test specification [10], [1], [71]

3) Scrum: Scrum is a lightweight framework for agile de- JavadocMiner is one of such NLP-based tools that developers
velopment and is very popular. Scrumconix supporting scrum can easily embed with Eclipse IDE [83].
proved to be a valuable and lightweight tool to document and
C. (RQ3) How can the tools and methods overcome the
understand a software project [59].
documentation challenges in agile software development?
4) User story: The user stories explain how the software
will work for the users and provide an essential source for the Agile methods or tools that have tried to address the chal-
design of the software according to user needs [1]. Methods lenges in dynamic contexts have gained much interest among
such as the COSMIC method [20], [65] can measure the practitioners and researchers [11]. Keeping that in mind,
quality of user stories to generate high-quality documentation. different researchers attempted to identify those challenges and
5) Traceability: Traceability tools like Trace++ support the built tools that provide on-demand solutions [25]. We listed
transition from traditional to agile methodologies. They offer all agile challenges in table IV that our previously mentioned
traceability between documents generated during conventional tools and methods attempted to resolve. Figure 2 represents a
software development and agile methods [28]. In addition, number of tools/methods that resolved a particular challenge.
TraceMan provides traces to critical agile artifacts [10].
6) API/Web service: In this category, we found a tool
called Docio which can generate API documents with I/O
examples [38]. This tool is more like the popular REST API
documentation generation tool Swagger but only supports the
C programming language [79].
7) Flow chart: A few tools emphasize providing mean-
ingful graphical diagrams either based on source code or
requirements [46], [69]. Flowgen, CLARET, and TCC are
some of the tools in this category.
8) Architectural: Experts ascertained the lack of documen-
tation and architectural design in agile projects [60]. Abstract
specification tool in this category assists the architects in or-
ganizing relevant information regarding the architecture while
creating design and architecture blueprints, thus reducing the
effort of documentation [31]. Also, Active Documentation Fig. 2. Number of tools/methods resolving a particular challenge
Software Design (ADSD) is an approach that enables incor-
porating domain documentation to agile development, while 1) Minimal documentation: One of the primary challenges
having the processes adaptive [67]. in agile documentation is to keep the documentation minimal
9) View based: View-based software documentation en- [16], [21]. Many documentation generation tools that generate
ables different perspectives on the software system and en- documentation from source code and chart, diagram, and
ables the explicit and simultaneous modeling of all of those flowchart-based documentation evolved to keep documentation
viewpoints as views in the documentation [11]. minimum and simple. Practitioners must keep minimal doc-
10) NLP-based: Researchers are aware of integrating mod- umentation to enhance agile software products, and the tool
ern NLP-based techniques and tools into the source code simul loco comments may answer this problem. Simul loco
comments where documentation is only available in the documentation is extremely useful [66]. Moreover, GitHub
form of source code comments. As a result, these tools di- plus Markdown support options so that reviewers can give a
rectly contribute to determining the quality of documentation. quick review, and it only takes a few minutes for a minor
TABLE III
T OOLS AND METHODS USED IN AGILE SOFTWARE DOCUMENTATION

No. Documentation Tools/Methods Studies that re- Role

type ported the prac-
tice
1 Source code based simul loco [66] Creates a graphical comment layer over source code that can contain any
documentation resource for documentation [66].
doxygen [55], [44] JavaDoc or docstring like documentation tool for Java, C++, Python, and
other languages [55].
JavadocMiner [44], [83], [43] Wrapper of JavaDoc and provides quality assessments and recommenda-
tions on how Javadoc comments can be improved [44].
GitHub plus mark- [48] Agile ’Docs Like Code’ solution that puts documentation close to the code
down while software development tools and techniques are applied [48].
Graphical UML [14], [77], [72], Graphical UML class models for source code in continuous agile develop-
class models [23], [15], [53], ment [14].
[51], [64]
XML_DocTracker [8] Produces the software requirements specification (SRS) from the source
codes if the SRS did not exist for that particular software [8].
2 Wiki based Wikis [9], [73], [41] Provides a collaborative environment that people use to co-author HTML-
based information [9].
sprintDoc [80] Works with issue tracker, wikis, VCS, IDE [80].
XSDoc [80], [5], [6] Minimizes the development–documentation gap by making documentation
more user-friendly and attractive to developers [5].
3 Scrum Scrumconix [59] Composition of scrum and ICONIX methods that uses a lightweight
approach to document in AGSD environments [59].
4 User stories COSMIC method [20], [24] Assesses the quality of the documentation by analyzing how functional
processes are documented in the requirements, such as in the user stories
[20].
CMMI [3], [52] Divides the goals into two parts and emphasizes that the product must be
delivered on time and meet all of the specified standards [3].
LAQF [42] Lightweight document oriented reusable agile quality framework [42].
5 Traceability TraceMan [10] Traces among user stories, traditional requirements documents, test speci-
fications, architecture design, and source code [10].
Trace++ [28] Inherits traditional traceability relationships in order to support the transi-
tion from traditional to ASD [28].
6 API/Web Service Docio [38] Documents API Input/Output with parameter and response type [38].
7 Flow chart or Dia- Flowgen [46] Generates flowcharts from annotated C++ source code and high-level UML
grams activity diagrams, one for each function or method in the C++ sources [46].
CLARET [39] Facilitates functionality to create the use case specifications using natural
language [39].
Ticket-commit [68], [69] Visually represents time-series commit activities with issued tickets [68].
network chart
(TCC)
8 Architectural Abstract specifica- [31] Contains the most relevant and essential information on the architecture
tion tool solution [31].
Active [67] Provides an architectural design in which domain knowledge is represented
Documentation explicitly and is isolated from other segments of code [67].
Software Design
(ADSD)
9 View based View-based [11] Utilizes existing software modeling techniques and improves the current
software methods of software documentation [11].
documentation
10 NLP based JavadocMiner [83] Provides a complete environment for embedding NLP into software devel-
opment [83].
TABLE IV
T HE SOLUTION PROVIDED BY TOOLS AND METHODS TO CERTAIN CHALLENGES

No. Challenge Description Tools/Methods Solutions

1 Minimal The lack of documentation imposes Source code based documentation Generates minimal documentation
documentation a variety of problems including the (simul loco [66], doxygen [44], with a very little effort. The doc-
[16], [21], [47] inability to scale the software and add [55], JavadocMiner [43], [44], [83], umentation can be either generated
new members. [16] GitHub plus markdown [48], Graph- from the source code comments or
ical UML class models [14], [15], XML or YAML or JSON file.
[23], [51], [53], [64], [72], [77],
XML_DocTracker [8]), Wiki based
(Wikis [9], [41], [73], sprintDoc [80],
XSDoc [5], [6], [80]), Flow chart or
Diagrams (Flowgen [46], CLARET
[39], Ticket-commit network chart
(TCC) [68], [69]), Abstract specifi-
cation tool [31]
2 Neglect of Customers often prioritize core func- TraceMan [10] Enables traceability among non-
non-functional tionality over non-functional require- functional requirements.
requirements ments (NFRs) such as scalability,
[16], [22], [47], maintainability, portability, safety, or
[49], [74] performance. [16], [50]
3 Inadequate As further requirements are known, Architectural (Abstract specification Generate architecture design with rel-
Architecture [7], the architecture designed by the de- tool [31], Active Documentation evant and updated information.
[63] velopment team during the initial Software Design (ADSD) [67])
phases may become outdated or in-
adequate. [63]
4 Lack of Tracing becomes challenging when Traceability (TraceMan [10], Trace appropriate user stories or dif-
traceability dealing with large scale or distributed Trace++ [28]) ferent artifacts even if the product
[18], [35], [61] software development efforts. [18] scales in the future.
5 Mediocre user Lack of proper user stories leads to User stories based (COSMIC method Measure the quality of user stories
stories [17], failure to achieve an overview of the [20], [24], CMMI [3], [52], LAQF and help to write high-quality user
[19], [74] product for team members. [19], [62] [42]), TraceMan [10] stories.
6 Others [18] API/Web Service (Docio [38]), View Generate API documentation from
based (View-based software docu- JSON file or supports view based
mentation [11]), Scrum (Scrumconix software documentation.
[59])

update. A document can be improved easily and continu- of traceability relations combining the various artifacts [28].
ously [48]. Abstract specification tool proposes a considerably 5) Mediocre user stories: Although user stories are essen-
shorter abstract specification document, requiring minimal tial for ASD, people struggle to document high-quality user
documentation efforts and resulting in shorter documentation stories. Even user stories mentioned in the current dataset are
that is easier to review, update, and communicate [31]. of poor quality [19]. TraceMan produces high-quality user
2) Neglect of non-functional requirements: The effect of stories by having detailed traces of user store information [10].
requirements changes on the architecture is crucial. It was 6) Others: Some tools resolve the complex API documen-
difficult to trace precisely which architectural decisions had tation challenges by creating API documentation with ease
to be reconsidered because of the lack of traceability between [38]. In addition, there are some tools such as Scrumconix
the textual requirements specification documents and the archi- [59], and view-based software documentation that cover chal-
tectural models. TraceMan fixes this since the trace links are lenges posed in the area of scrum and view-based [11].
created during the artifacts’ creation. As a result, we can better
understand the functional and non-functional requirements IV. T HREATS TO VALIDITY
using TraceMan more accurately and consequently [10]. The threats to our systematic literature review are the
3) Inadequate Architecture: The primary goals of agile specification of the candidate pool of papers and primary
development are flexibility, minimalism, and collaboration. study selection bias. We selected our primary pools of studies
Abstract specification tool achieves these by creating a short through database searches and used keywords. Our keywords
and focused architecture document [31]. were very precise, and we obtained a good number of papers.
4) Lack of traceability: Conventional agile projects entail However, we may missed some papers due to our specific
intensive labor work to generate and maintain traceable links. search string.
Consequently, lack of traceability provides a weak layer over We also used a specific period to select our studies, which
the software system no matter how much flexible the system might have discarded relevant papers. On the other hand,
is [18]. On the other hand, trace++ generates a large number we relied on IEEE Xplore for a primary pool of studies,
which threatens to have a complete set of primary studies. To [12] W. Behutiye, P. Rodríguez, M. Oivo, S. Aaramaa, J. Partanen, and
mitigate this risk, we performed both backward and forward A. Abhervé. How agile software development practitioners perceive
the need for documenting quality requirements: a multiple case study.
snowballing, which eventually resulted in a collection of In 2020 46th Euromicro Conf. on Software Engineering and Advanced
papers from other databases like ACM, Springer, etc. We Applications (SEAA), pages 93–100, 2020.
followed the standard inclusion and exclusion criteria, which [13] W. Behutiye, P. Seppänen, P. Rodríguez, and M. Oivo. Documentation of
quality requirements in agile software development. In Evaluation and
might still introduce some personal bias. Assessment in Software Engineering, EASE ’20, page 250–259, 2020.
[14] E. Braude. Incremental uml for agile development: Embedding uml
V. C ONCLUSION class models in source code. In 2017 IEEE/ACM 3rd Intl. Workshop on
Rapid Continuous Software Engineering (RCoSE), 2017.
Working software gets priority over detailed documentation [15] E. Braude and J. Van Schooneveld. Poster: Incremental uml for agile
development with prexel. In 2018 IEEE/ACM 40th Intl. Conf. on
in agile software development. Even though documentation is Software Engineering: Companion (ICSE-Companion), 2018.
less of a priority in ASD, studies have shown that a minimal [16] L. Cao and B. Ramesh. Agile requirements engineering practices: An
level of documentation is essential. This research aimed to empirical study. IEEE Software, 25(1):60–67, 2008.
[17] F. E. Castillo-Barrera, M. Amador-García, H. Pérez-González, and F. E.
identify key elements to record in ASD and locate appropriate Martínez-Pérez. Agile evaluation of the complexity of user stories using
tools to aid in documentation. We conducted a systematic the bloom’s taxonomy. In 2017 Intl. Conf. on Computational Science
literature review to identify essential information in agile and Computational Intelligence (CSCI), pages 1047–1050, 2017.
[18] J. Cleland-Huang. Traceability in Agile Projects, pages 265–275.
documentation and the effectiveness of current methodologies Springer London, London, 2012.
and tools in agile software development. As a result, we have [19] F. Dalpiaz and S. Brinkkemper. Agile requirements engineering with
compiled a list of essential elements in agile documentation user stories. In 2018 IEEE 26th Intl. Requirements Engineering Conf.
(RE), pages 506–507, 2018.
and tools and approaches that can help alleviate the documen- [20] J.-M. Desharnais, B. Kocaturk, and A. Abran. Using the cosmic method
tation challenges. to evaluate the quality of the documentation of agile user stories. In Intl.
Our findings will aid in understanding key aspects of agile Workshop on Software Measurement and the 6th Intl. Conf. on Software
Process and Product Measurement, 2011.
documentation and how agile documentation tools and ap- [21] A. Deuter. Slicing the v-model – reduced effort, higher flexibility. In
proaches function. In the future, we want to map the relation- 2013 IEEE 8th Intl. Conf. on Global Software Engineering, 2013.
ships between these technologies and develop a method that [22] D. Domah and F. J. Mitropoulos. The nerv methodology: A lightweight
process for addressing non-functional requirements in agile software
can be used as a one-stop solution for agile documentation. development. In SoutheastCon 2015, pages 1–7, 2015.
We also intend to conduct a multi-vocal literature review to [23] S. Dragicevic, S. Celar, and L. Novak. Use of method for elicitation,
find more industry concerns and solutions. Finally, our future documentation, and validation of software user requirements (medov) in
agile software development projects. In Intl. Conf. on Computational
plan also involves a survey of agile practitioners to see the Intelligence, Communication Systems and Networks, pages 65–70, 2014.
usefulness of this article. [24] J.-F. Dumas-Monette and S. Trudel. Requirements engineering quality
revealed through functional size measurement: An empirical study in an
agile context. In Intl. Workshop on Software Measurement and the Intl.
R EFERENCES Conf. on Software Process and Product Measurement, 2014.
[25] W. R. Fitriani, P. Rahayu, and D. I. Sensuse. Challenges in agile software
[1] . Iso/iec/ieee intl. standard - systems and software engineering – development: A systematic literature review. In 2016 Intl. Conf. on
developing user documentation in an agile environment. ISO/IEC/IEEE Advanced Computer Science and Information Systems (ICACSIS), 2016.
26515 First edition 2011-12-01; Corrected version 2012-03-15, pages [26] A. Forward and T. C. Lethbridge. The relevance of software documen-
1–36, 2012. tation, tools and technologies: A survey. In Proceedings of the 2002
[2] . Iso/iec/ieee intl. standard - systems and software engineering — ACM Symposium on Document Engineering, DocEng ’02, 2002.
developing information for users in an agile environment. ISO/IEC/IEEE [27] M. Fowler, J. Highsmith, et al. The agile manifesto. Software
26515:2018(E), pages 1–32, 2018. development, 9(8):28–35, 2001.
[3] S. K. Aggarwal, V. Deep, and R. Singh. Speculation of cmmi in [28] F. Furtado and A. Zisman. Trace++: A traceability approach to support
agile methodology. In 2014 Intl. Conf. on Advances in Computing, transitioning to agile software engineering. In 2016 IEEE 24th Intl.
Communications and Informatics (ICACCI), pages 226–230, 2014. Requirements Engineering Conf. (RE), pages 66–75, 2016.
[4] E. Aghajani, C. Nagy, O. L. Vega-Márquez, M. Linares-Vásquez, [29] W. Gerard, S. Overbeek, and S. Brinkkemper. Fuzzy artefacts: Formality
L. Moreno, G. Bavota, and M. Lanza. Software documentation issues of communication in agile teams. In 2018 11th Intl. Conf. on the Quality
unveiled. In Intl. Conf. on Software Engineering (ICSE), 2019. of Information and Communications Technology (QUATIC), 2018.
[5] A. Aguiar and G. David. Wikiwiki weaving heterogeneous software [30] D. D. Gregorio. How the business analyst supports and encourages
artifacts. In Intl. Symposium on Wikis, WikiSym ’05, page 67–74, 2005. collaboration on agile projects. In Intl. Systems Conf. SysCon 2012,
[6] A. Aguiar, G. David, and M. Padilha. Xsdoc: an extensible wiki-based 2012.
infrastructure for framework documentation. In JISBD, 2003. [31] I. Hadar, S. Sherman, E. Hadar, and J. J. Harrison. Less is more:
[7] F. Akbari and S. M. Sharafi. A review to the usage of concepts of Architecture documentation for agile development. In 2013 6th Intl.
software architecture in agile methods. In Intl. Symposium on Instrumen- Workshop on Cooperative and Human Aspects of Software Engineering
tation Measurement, Sensor Network and Automation (IMSNA), 2012. (CHASE), 2013.
[8] H. Aman and R. Ibrahim. Xml_doctracker: Generating software re- [32] M. Hammad, I. Inayat, and M. Zahid. Risk management in agile
quirements specification (srs) from xml schema. In 2016 Intl. Conf. on software development: A survey. In 2019 Intl. Conf. on Frontiers of
Information Science and Security (ICISS), pages 1–5, 2016. Information Technology (FIT), pages 162–1624, 2019.
[9] S. Ambler. Agile modeling: effective practices for extreme programming [33] P. Heck and A. Zaidman. A framework for quality assessment of
and the unified process. John Wiley & Sons, 2002. just-in-time requirements: the case of open source feature requests.
[10] P. O. Antonino, T. Keuler, N. Germann, and B. Cronauer. A non-invasive Requirements Engineering, 22(4):453–473, 2017.
approach to trace architecture design, requirements specification and [34] A. Hess, P. Diebold, and N. Seyff. Towards requirements communication
agile artifacts. In 23rd Australian Software Engineering Conf., 2014. and documentation guidelines for agile teams. In 2017 IEEE 25th Intl.
[11] J. Bayer and D. Muthig. A view-based approach for improving Requirements Engineering Conf. Workshops (REW), 2017.
software documentation practices. In Intl. Symposium and Workshop [35] N. N. Hidayati and S. Rochimah. Requirements traceability for de-
on Engineering of Computer-Based Systems (ECBS’06), 2006. tecting defects in agile software development. In 2020 10th Electrical
Power, Electronics, Communications, Controls and Informatics Seminar [58] R. Phalnikar, V. Deshpande, and S. Joshi. Applying agile principles
(EECCIS), pages 248–253, 2020. for distributed software development. In 2009 Intl. Conf. on Advanced
[36] J. Holvitie, S. A. Licorish, R. O. Spínola, S. Hyrynsalmi, S. G. Computer Control, pages 535–539, 2009.
MacDonell, T. S. Mendes, J. Buchan, and V. Leppänen. Technical debt [59] L. T. Portela and G. Borrego. Scrumconix: Agile and documented
and agile software development practices and processes: An industry method to agsd. In 2016 IEEE 11th Intl. Conf. on Global Software
practitioner survey. Information and Software Technology, 2018. Engineering (ICGSE), pages 195–196, 2016.
[37] A. Jarz˛ebowicz and K. Połocka. Selecting requirements documentation [60] C. R. Prause and Z. Durdik. Architectural design and documentation:
techniques for software projects: A survey study. In 2017 Federated Waste in agile development? In 2012 Intl. Conf. on Software and System
Conf. on Computer Science and Information Systems (FedCSIS), 2017. Process (ICSSP), pages 130–134, 2012.
[38] S. Jiang, A. Armaly, C. McMillan, Q. Zhi, and R. Metoyer. Docio: [61] A. Qusef. Test-to-code traceability: Why and how? In 2013 IEEE Jordan
Documenting api input/output examples. In 2017 IEEE/ACM 25th Intl. Conf. on Applied Electrical Engineering and Computing Technologies
Conf. on Program Comprehension (ICPC), pages 364–367, 2017. (AEECT), pages 1–8, 2013.
[39] D. N. Jorge, P. D. L. Machado, E. L. G. Alves, and W. L. Andrade. [62] I. K. Raharjana, D. Siahaan, and C. Fatichah. User story extraction
Integrating requirements specification and model-based testing in agile from online news for software requirements elicitation: A conceptual
development. In 2018 IEEE 26th Intl. Requirements Engineering Conf. model. In 2019 16th Intl. Joint Conf. on Computer Science and Software
(RE), pages 336–346, 2018. Engineering (JCSSE), pages 342–347, 2019.
[40] R. Kasauli, G. Liebel, E. Knauss, S. Gopakumar, and B. Kanagwa. [63] B. Ramesh, L. Cao, and R. Baskerville. Agile requirements engineering
Requirements engineering challenges in large-scale agile system devel- practices and challenges: an empirical study. Info Systems Journal,
opment. In Intl. Requirements Engineering Conf. (RE), 2017. 20(5):449–480, 2010.
[41] R. Kavitha and M. Irfan Ahmed. A knowledge management framework [64] A. S. B. Rani and A. R. N. B. Kamal. Text mining to concept mining:
for agile software development teams. In 2011 Intl. Conf. on Process Leads feature location in software system. In 2018 IEEE Intl. Conf. on
Automation, Control and Computing, pages 1–5, 2011. Computational Intelligence and Computing Research (ICCIC), 2018.
[42] M. A. Khalid, T. Anees, and A. Moeed. Laqf: Lightweight document [65] A. Read and R. O. Briggs. The many lives of an agile story: Design
oriented, reusable agile quality framework. In 2019 Intl. Conf. on processes, design products, and understandings in a large-scale agile
Innovative Computing (ICIC), pages 1–8, 2019. development project. In 2012 45th Hawaii Intl. Conf. on System
[43] N. Khamis, J. Rilling, and R. Witte. Assessing the quality factors found Sciences, pages 5319–5328, 2012.
in in-line documentation written in natural language: The javadocminer. [66] S. G. Rojas and J. M. C. Mora. Source code documentation simul loco.
Data & Knowledge Engineering, 87:19–40, 2013. In 7th Iberian Conf. on Info Systems and Tech (CISTI 2012), 2012.
[44] N. Khamis, R. Witte, and J. Rilling. Automatic quality assessment of [67] E. Rubin and H. Rubin. Supporting agile software development through
source code comments: The javadocminer. In C. J. Hopfe, Y. Rezgui, active documentation. Requirements Engineering, 16(2), Jun 2011.
E. Métais, A. Preece, and H. Li, editors, Natural Language Process- [68] S. Saito, Y. Iimura, A. K. Massey, and A. I. Antón. Discovering undocu-
ing and Information Systems, pages 68–79, Berlin, Heidelberg, 2010. mented knowledge through visualization of agile software development
Springer Berlin Heidelberg. activities. Requirements Engineering, 23(3):381–399, 2018.
[45] B. Kitchenham and S. Charters. Guidelines for performing systematic [69] S. Saito, Y. Iimura, A. K. Massey, and A. I. Antón. How much
literature reviews in software engineering. 2007. undocumented knowledge is there in agile software development?: Case
study on industrial project using issue tracking system and version
[46] D. A. Kosower, J. J. Lopez-Villarejo, and S. Roubtsov. Flowgen:
control system. In 2017 IEEE 25th Intl. Requirements Engineering Conf.
Flowchart-based documentation framework for c++. In 2014 IEEE 14th
(RE), pages 194–203, 2017.
Intl. Working Conf. on Source Code Analysis and Manipulation, 2014.
[70] B. Selic. Agile documentation, anyone? IEEE Software, 26(6), 2009.
[47] M. Käpyaho and M. Kauppinen. Agile requirements engineering with
[71] M. Shafiq and U. s. Waheed. Documentation in agile development
prototyping: A case study. In 2015 IEEE 23rd Intl. Requirements
a comparative analysis. In 2018 IEEE 21st Intl. Multi-Topic Conf.
Engineering Conf. (RE), pages 334–343, 2015.
(INMIC), pages 1–8, 2018.
[48] L. Lee. Extended abstract: Documentation development practice in [72] A. K. Sharma, V. Deep, and N. Garg. An efficient way of articulation
open source startups - take pingcap as an example. In 2019 IEEE Intl. or suppression in agile methodologies. In Confluence 2013: The Next
Professional Communication Conf. (ProComm), pages 255–256, 2019. Generation Information Technology Summit (4th Intl. Conf.), 2013.
[49] R. R. Maiti and F. J. Mitropoulos. Capturing, eliciting, predicting [73] C. Silveira, J. P. Faria, A. Aguiar, and R. Vidal. Wiki based requirements
and prioritizing (cepp) non-functional requirements metadata during the documentation of generic software products. In Australian Workshop on
early stages of agile software development. In SoutheastCon 2015, 2015. Requirements Engineering (AWRE), 2005.
[50] R. R. Maiti and F. J. Mitropoulos. Capturing, eliciting, and prioritizing [74] H. F. Soares, N. S. Alves, T. S. Mendes, M. Mendonça, and R. O.
(cep) nfrs in agile software engineering. In SoutheastCon 2017, 2017. Spínola. Investigating the link between user stories and documentation
[51] D. Matheson. Modeling requirements: The customer communication. debt on software projects. In 2015 12th Intl. Conf. on Information
In 2014 IEEE 5th Intl. Workshop on Requirements Prioritization and Technology - New Generations, pages 385–390, 2015.
Communication (RePriCo), pages 15–24, 2014. [75] S. M. Sohan, F. Maurer, C. Anslow, and M. P. Robillard. A study of
[52] J. R. Miller and H. M. Haddad. Challenges faced while simultaneously the effectiveness of usage examples in rest api documentation. In 2017
implementing cmmi and scrum: A case study in the tax preparation IEEE Symposium on Visual Languages and Human-Centric Computing
software industry. In 2012 Ninth Intl. Conf. on Information Technology (VL/HCC), pages 53–61, 2017.
- New Generations, pages 314–318, 2012. [76] I. Sommerville. Software documentation. Software engineering, 2, 2001.
[53] V. C. Nguyen and X. Qafmolla. Agile development of platform [77] C. J. Stettina, W. Heijstek, and T. E. Fægri. Documentation work in agile
independent model in model driven architecture. In 2010 Third Intl. teams: The role of documentation formalism in achieving a sustainable
Conf. on Information and Computing, volume 2, pages 344–347, 2010. practice. In 2012 Agile Conf., pages 31–40, 2012.
[54] P. A. O. Salo. Agile methods in european embedded software develop- [78] C. J. Stettina and E. Kroon. Is there an agile handover? an empirical
ment organisations: a survey on the actual use and usefulness of extreme study of documentation and project handover practices across agile
programming and scrum. IET Software, 2:58–64(6), 2008. software teams. In 2013 Intl. Conf. on Engineering, Technology and
[55] A. Oboler and I. Sommerville. Research documentation guidelines - Innovation (ICE) IEEE Intl. Technology Management Conf., 2013.
capturing knowledge, improving research. In Fourth Intl. Conf. on [79] V. Surwase. Rest api modeling languages-a developer’s perspective. Int.
Information Technology (ITNG’07), 2007. J. Sci. Technol. Eng, 2(10):634–637, 2016.
[56] M. Ormsby and C. Busby-Earle. A standardized procedure to conceptu- [80] S. Voigt, D. Hüttemann, and A. Gohr. sprintdoc: Concept for an agile
alizing and completing user stories. In 2017 Intl. Conf. on Computational documentation tool. In 2016 11th Iberian Conf. on Information Systems
Science and Computational Intelligence (CSCI), pages 934–939, 2017. and Technologies (CISTI), pages 1–6, 2016.
[57] J. Pasuksmit, P. Thongtanunam, and S. Karunasekera. Towards just- [81] S. Voigt, J. von Garrel, J. Müller, and D. Wirth. A study of documen-
enough documentation for agile effort estimation: What information tation in agile software projects. In Proceedings of the 10th ACM/IEEE
should be documented? In 2021 IEEE Intl. Conf. on Software Mainte- Intl. Symposium on Empirical Software Engineering and Measurement,
nance and Evolution (ICSME), pages 114–125, 2021. ESEM ’16, 2016.
[82] M. K. Wadiwala and A. F. M Ishaq. Use of design and modeling in
agile software development. In 2010 Second Intl. Conf. on Engineering
System Management and Applications, pages 1–5, 2010.
[83] R. Witte, B. Sateli, N. Khamis, and J. Rilling. Intelligent software
development environments: Integrating natural language processing with
the eclipse platform. In C. Butz and P. Lingras, editors, Advances
in Artificial Intelligence, pages 408–419, Berlin, Heidelberg, 2011.
Springer Berlin Heidelberg.
[84] C. Wohlin. Guidelines for snowballing in systematic literature studies
and a replication in software engineering. In Proceedings of the 18th
Intl. Conf. on evaluation and assessment in software engineering, 2014.