ArticlePDF Available

Significance of Software Documentation in Software Development Process

Authors:

Abstract and Figures

Incorrect, missing, brief, or out of data documentation are considered some of major attributes which can be responsible for poor software quality. Therefore, software development associations need to have appropriate document control strategies. For every software irrespective of its size and complexity software documentation is generated. Inappropriate generation or omissions of documentation sometimes even leads to software failure. Consequently, software engineers should pay substantial amount of time concentrating on generation of software documentation. Hence, through this paper our aim is to focus on the importance of software project documentation. The paper is divided into four sections; first section is introductory, followed by literature review. Section three represents finding and analysis from literature review, followed by concluding section.
Content may be subject to copyright.
Copyright © 2014 IJEIR, All right reserved
410
International Journal of Engineering Innovation & Research
Volume 3, Issue 4, ISSN: 2277 5668
Significance of Software Documentation in Software
Development Process
Mr. Vikas S. Chomal
Assistant Professor
The Mandvi Education Society Institute of
Computer Studies, Mandvi, Gujarat, India
Email: vikschomal80@gmail.com, vikschomal@yahoo.co.in
Dr. Jatinderkumar R. Saini
Director (I/C) & Associate Professor
Narmada College of Computer Application,
Bharuch, Gujarat, India
Email: saini_expert@yahoo.com
Abstract Incorrect, missing, brief, or out of data
documentation are considered some of major attributes
which can be responsible for poor software quality.
Therefore, software development associations need to have
appropriate document control strategies. For every software
irrespective of its size and complexity software
documentation is generated. Inappropriate generation or
omissions of documentation sometimes even leads to software
failure. Consequently, software engineers should pay
substantial amount of time concentrating on generation of
software documentation. Hence, through this paper our aim
is to focus on the importance of software project
documentation. The paper is divided into four sections; first
section is introductory, followed by literature review. Section
three represents finding and analysis from literature review,
followed by concluding section.
Keywords Software Documentation, Software
Development, Software Projects.
I. INTRODUCTION
In broad requisites, documentation is any communicable
matter such as text, video, audio, CD, DVD etc., or
combinations thereof used to describe some characteristics
of an object, system or procedure. It is frequently used in
today’s information period to mean engineering or
software documentation, which is typically paper books or
computer readable files that portray the structure and
components, or on the other hand, operation, of a
system/product.
Software documentation is an essential feature of both
software projects and software engineering in common. In
piece of evidence, documentation engineering has become
an accepted sub-domain in the software engineering
society. The task of documentation in a software
engineering milieu is to commune information to its
spectators and instils knowledge of the system it describes
[3].
Documentation is requisite in software development. Even
though every software development project is exclusive
and produces diverse categories of documents, different
amount of documentation, and may employ different
documentation methods and notations, we need to be able
to control the documentation produced in software
development projects in a uniform manner [2][16].
According to Cock & Visconti [9] a fundamental goal of
software engineering is to produce the best possible
working software along with the best supporting
documentation.
Software development is partly a learning and
communication process. Software developers need to
communicate with each other and also with various
interest groups of the system to be developed, such as
customers, marketing people, end users, service personnel,
and authorities. Documentation is the basis for
communication in software development organizations as
well as between development organizations and the
interest groups of the system to be developed. To ensure
efficient communication, all communicating parties need
to be able to identify various software documents, and, to
ensure that the right information is found, all
communicating parties should be able to anticipate what
information is in each document [15][22].
According to Sommerville [12], documents associated
with a software project and the systems being developed
have a number of associated requirements:
1. They should act as a communication medium between
members of the development team.
2. They should be a system information repository to be
used by maintenance engineers.
3. They should provide information for management to
help them plan, budget and schedule the software
development process.
4. Some of the documents should tell users how to use and
administer the system.
Documentation produced falls into two classes:
1. Process documentation: These documents record the
process of development and maintenance. Plans,
schedules, process quality documents and organizational
and project standards are process documentation.
2. Product documentation: This documentation describes
the product that is being developed. System
documentation describes the product from the point of
view of the engineers developing and maintaining the
system; user documentation provides a product description
that is oriented towards system users.
II. RELATED LITERATURE REVIEW
Laitinen [15] puts forward that software development is
supposed to be documentation-oriented, which means that
documents are considered to be the most essential and
valuable products of the development process.
Documentation-orientedness involves considering such
computer-process able products as source program
modules and batch-files as documents. On the other hand,
a product such as executable machine code is regarded as
Copyright © 2014 IJEIR, All right reserved
411
International Journal of Engineering Innovation & Research
Volume 3, Issue 4, ISSN: 2277 5668
a by-product in the development process, because in a
development environment we can always derive correct
executable machine code when we have the correct
documents. The executable machine code is essential to
the user of a computer system, but it is considered less
important to the software developers. Further Laitinen [15]
classifies software documentation into five types of
classes, which are illustrated in Table 1. There are five
documents classes: 1) Software Descriptions describe a
system "as it is" and the executable machine code is
derived according to those, 2) Utilization Documents are
needed in order that the system derived from Software
Descriptions might be used, 3) Development Plans are
needed to carry out the development of Software
Descriptions and Utilization Documents in a disciplined
manner, 4) Quality Control Documents are needed to
control the quality of the Software Descriptions and
Utilization Documents, and 5) Administrative Documents
are needed to establish the financial basis for the software
development and to control how well the development
proceeds as planned.
Table 1: Classes of Software Documents [15]
Software Descriptions
Utilization
Documents
Development Plans
Quality Control
Documents
Administrative
Documents
Main Software
Descriptions
Short System Description
Requirement Description
Architecture Description
Implementation Description
Configuration Description
Software Description Appendices
Terminology Description
Internal Message Description
External Message Description
Record Description
User Interface Description
Process Description
Initialization Description
User's Manual
Operator's Manual
Installation Manual
Service Manual
User's Help
Operator's Help
Installation Help
Service Help
Responsibility Plan
Work Breakdown Plan
Schedule Plan
Expense Plan
Phase Plan
Risk Plan
Test Plan
Acceptance Plan
Manual Plan
Method Plan
Tool Plan
Reporting Plan
Quality Plan
Documentation Plan
Version control Plan
Analysis Request
Information Request
Reader's Report
Review Report
Inspection Report
Test Report
Review Call
Inspection Call
Test Call
Development
Contract
Extended
Contract
Maintenance
Contract
Contract Review
Minutes
Project Meeting
Minutes
Chomal and Saini [26, 30] in their recent works listed
the causes that lead to software project failures. Chomal
and Saini [28] in another work considered documentation
of software projects prepared by students as a source for
data collection and analyzed it. Chomal and Saini [27, 29]
in still another work had also described how software
documentation can be used as a knowledge management
model for improving quality of software as well as
database.
Cock & Visconti [9] elucidate that empirical data shows
that software documentation products and processes are
key components of software quality. These studies show
that poor quality, out of date, or missing documentation is
a major cause of errors in software development and
maintenance. For example, the majority of defects
discovered during integration testing are design and
requirements defects, e.g. defects in documentation that
were introduced before any code was written.
Hopkins & Jeroow [14] describes documentation as,
“Documentation is the castor oil of programming.
Managers know it must be a good because the
programmers hate it so much”.
Hunt & Thomas [11] explain that communication is
achieved only when information is being conveyed. Based
on the assumption that documentation is communication,
the goal of a particular software document is to convey
information. This information may not necessarily be
completely accurate or consistent. Chapin [8] states that
the value of software can be determined by many factors.
One of the four main issues related to software value is its
documentation. Chapin describes several main concerns
regarding documentation: quality, obsolescence or missing
content. To preserve and enhance software value, Chapin
recommends to “keeping the documentation current and
trustworthy” [8]. It is important to note that merely being
current and trustworthy do not necessarily imply
applicable or useful.
Forward [3] describes the relationship between models,
documents and documentation below in Figure 1.
Fig.1. The relationship between models, documents,
source code, and documentation [3].
Curtis et al [10] believe that documentation should focus
on how requirements and design decisions were made,
represented, communicated and changed over the lifespan
Copyright © 2014 IJEIR, All right reserved
412
International Journal of Engineering Innovation & Research
Volume 3, Issue 4, ISSN: 2277 5668
of a software system. As well, documentation should
describe the impact of the current system on future
development processes. Their study involved interviewing
personnel from seventeen large software projects. Their
analysis focused on the problems of designing large
software systems; but many results report directly about
the use (and misuse) of documentation in a software
project. Forward & Lethbridge [1] expresses
documentation as; the software documentation includes
any artefact whose purpose is to communicate information
about the software system to which it belongs. These
artefacts include requirement, specification, and
architectural and detailed design documents. These
documents are geared to individuals involved in the
production of that software, such as managers, project
leaders, developers and customers.
III. FINDINGS AND ANALYSIS
In this section we present the findings from the literature
reviewed in Table 2 about the relevant importance of
software project documentation.
Table 2: Analysis of Literature
Author(s)
Major Contribution
Thomas, Bill, Dennis Smith
and Scott Tilley [24]
They put forward that, software engineers rely on program documentation as an
aid in understanding the functional nature, high-level design, and
implementation details of complex applications. However, no one really knows
what types of documentation are truly useful to software engineers to aid system
understanding. This workshop focuses on issues related to this fundamental
problem, such as what formats the documentation should take, who should
produce it, and when. The juxtaposition of a technical communication audience
with software engineering researchers and practitioners will provide new
insights into the problem.
Andrew Forward, Timothy
Lethbridge [1]
The goals of their survey was to uncover the perceived relevance (or lack
thereof) of software documentation, and the tools and technologies used to
maintain, verify and validate such documents. The survey results highlight the
preferences for and aversions against software documentation tools. Participants
agree that documentation tools should seek to better extract knowledge from
core resources. These resources include the system's source code, test code and
changes to both. Resulting technologies could then help reduce the effort
required for documentation maintenance, something that is shown to rarely
occur. Their data reports compelling evidence that software professionals value
technologies that improve automation of the documentation process, as well as
facilitating its maintenance.
Antonial, G., Canfora, G., De
Lucia, A. and Merlo, E. [4]
Their studies revealed that software system documentation is almost always
expressed informally, in natural language and free text. Examples include
requirement specifications, design documents, user manual pages, system
development journals, error logs and related maintenance reports. They propose
an approach to establish and maintain traceability links between the source code
and free-text documents. A premise of our work is that programmers use
meaningful names for program's items, such as functions, variables, types,
classes and methods. They believe that the application domain knowledge that
programmers process when writing the code is often captured by the mnemonics
for identifiers; therefore, the analysis of these mnemonics can help to associate
high-level concepts with program concepts, and vice versa. In this paper, the
approach is applied to software written in an object-oriented (OO) language,
namely C++, to trace classes to manual sections
Nasution. M.F.F,
Weistroffer. H.R [18]
They proposed that agile software development methods seem inherently
suitable for today's quick-paced business environment as they shorten the time
to develop new systems and typically incur lower development costs compared
to the conventional systems development life cycle (SDLC) approach. Software
development project failures using conventional SDLC are often attributed to
project delays, resulting in budget overruns. On the other hand, a well planned
and documented systems development project is more likely to result in a
system that meets the expectations of both the intended users and the
software engineers. This paper takes another look at conventional SDLC
methodology by focusing on an aspect that is often overlooked in systems
development practice, namely the significance of good documentation.
Copyright © 2014 IJEIR, All right reserved
413
International Journal of Engineering Innovation & Research
Volume 3, Issue 4, ISSN: 2277 5668
Sulaiman. S, Sahibudding. S
[23]
They explained the importance of documentation stating that,
System documentation (SD) is undoubtedly vital as one of the sources
in software understanding. Despite its importance, practitioners are often
confronted with the problems related to SD. A number of tools have been
introduced in order to assist documenting activities. However such tools are still
not widely used because they generally fail to meet users' needs. Hence we have
conducted a survey in Malaysia with the main goal to study software engineers'
current practice during software development and maintenance in relation with
SD based on four types of data elements: characteristic, behaviour, belief and
attitude. At the very outset, we need to establish what kind of tools should be
introduced, why is it introduced and when or how should it be introduced to
meet their needs in documenting activities. The findings of the study will argue
whether it is relevant to introduce reverse engineering or a document generator
tool to serve required information early in the development stage.
Barker. T. T [5]
He indicated that, the field of software documentation is reviewed by examining
manual writing before and after 1985. Changes in the field include an increased
emphasis on satisfaction of users, improved management strategies and
improved design techniques. Three books on software documentation published
since 1988 are surveyed, and it is argued that the trends after 1985 reinforce a
social constructionist view of documentation
Briand. L. C [7]
Briand states that, it is a well-known fact that software documentation is, in
practice, poor and incomplete. Though specification, design, and test
documents-among other things-are required by standards and capability
maturity models (e.g., SEI CMM), such documentation does not exist in a
complete and consistent form in most organizations. When documents are
produced, they tend to follow no defined standard and lack information that is
crucial to make them understandable and usable by developers and maintainers.
Then a fundamental practical question, which motivated this keynote address, is
to better understand what type of documentation is required, what is needed to
support its completeness and consistency, and what is the level of precision
required for each type of document. These questions cannot be investigated at
that level of generality though. Answers are likely to be very context-dependent
if they are to be precise. They focus our attention here on object-oriented
development and the Unified Modelling Language (UML).
Walters, N.J, Beck, C.E [33]
To discover the similarities and differences between primary and secondary
computer manuals, and to account for the popularity of the secondary texts, two
best-selling books for word processing and spreadsheet programs are compared
to documentation supplied by the manufacturer. A heuristic for
analyzing software documentation based on cognitive and rhetorical principles
is developed and applied to the corporate documentation for (WordPerfect 5.0)
in contrast to Stewart's Using WordPerfect 5 from Que, and the
corporate documentation from `Lotus 1-2-3' in contrast to Gilbert and William’s
`The ABC's of 1-2-3 from Sybex.' It is shown that the trade texts from Que and
Sybex contain more conceptual background information than the
corporate documentation and differ in their rhetorical stance: the writers provide
a richer context by giving more examples for applying the software; the writers
provide global and structural frameworks; the writers use persuasive marketing
techniques to ease the reader's anxieties and remind them of the software's
benefits; and the writers identify themselves
Parnas, D.L., Vilkomir [19]
There experience and research based paper discusses the reasons
that software cannot be trusted and then explains how the use of greatly
improved documentation can make software more trustworthy. It shows how
tabular expressions can be used to prepare software documents that are both
precise and easily used by developers, inspectors, and testers. The paper reviews
a number of "tried and true" ideas and illustrates some new refinements in the
methods that resulted from recent research. It is intended both to tell developers
of techniques available to them and to suggest new research areas.
Remo. C. Boer, Hans van
Vliet [21]
In their work, they focuses on the effectiveness of documentation within a
development process is determined by the way in which the intentions of the
Copyright © 2014 IJEIR, All right reserved
414
International Journal of Engineering Innovation & Research
Volume 3, Issue 4, ISSN: 2277 5668
authors correspond to the expectations of the potential readers. Ideally, the
members of a development team share a certain understanding of (the role of)
the different types of documentation. However, since one's expectations of a
document are personal, and part of a tacitly formed mental model, we can
expect different levels of shared understanding between different development
team members. They elicited and analyzed the mental models
of software documentation from eight members of a single development team.
They found indeed different levels of shared understanding between different
people. To their surprise, the levels of shared understanding within the team
appear closely tied to the development process employed. From Conway's law
we know that an organization's structure is mirrored in the structure of
the software that the organization produces. Their findings suggest that the
organization's development process may likewise be mirrored in the extent to
which a development team shares a common frame of reference. Hence, the
development process followed may have implications for the effectiveness with
which development knowledge can be shared through software documentation.
Visconti. M , Cook C. R [32]
A system documentation process maturity model and assessment procedure
were developed and used to assess 91 projects at 41 different companies over a
seven year period. During this time the original version evolved into a total of
four versions based on feedback from industry and the experience gained from
the assessments. This paper reports the overall results obtained from the
assessments which strongly suggest that the practice of documentation is not
getting a passing grade in the software industry. The results show a clear
maturity gap between documentation practices concerned with defining policy
and practices concerned with adherence to those policies. The results further
illustrate the need to recognize the importance of improving
the documentation process, and to transform the good intentions into explicit
policies and actions.
Young F. H [34]
The author describes the development of a course at Rose-Hulman Institute of
Technology that integrates software engineering and software documentation. A
brief evaluation is followed by a discussion of future plans. It is pointed out that
the most significant benefit of the combined course is the
improved software engineering abilities of the students. The students see the
importance of presentation and writing skills in the software development
process. They apply these skills in ways that improve their ability to develop
large software systems
Lethbridge, T.C., Singer, J.
and Forward, A [17]
They delineates Software Engineering and focuses on the importance of
Software Documentation by stating that, Software engineering is a human task,
and as such we must study what software engineers do and think. Understanding
the normative practice of software engineering is the first step toward
developing realistic solutions to better facilitate the engineering process. They
conducted three studies using several data-gathering approaches to elucidate the
patterns by which software engineers (SEs) use and update documentation.
Their objective is to more accurately comprehend and
model documentation use, usefulness, and maintenance, thus enabling better
decision making and tool design by developers and project managers. Their
results confirm the widely held belief that SEs typically does not update
documentation as timely or completely as software process personnel and
managers advocate. However, the results also reveal that out-of-
date software documentation remains useful in many circumstances.
Qian Hu [20]
According to author, the software documentation is unpopular among many
developers at present while the documents are important for the staffs who work
for secondary development and software maintenance. For this phenomenon, a
teaching method of writing software documentation is proposed in this paper, in
which the software maintenance is the driving force to make students fully
understand and grasp the method of software documentation writing through an
upgrade and maintenance software project. And students learn to write
effective software documentation to establish the level and structure of the
document.
Copyright © 2014 IJEIR, All right reserved
415
International Journal of Engineering Innovation & Research
Volume 3, Issue 4, ISSN: 2277 5668
Vir Phoha [31]
While there is no universally recognized standard for software documentation,
there is a standard for documenting engineering and scientific software.
Developed by the American National Standards Institute (ANSI) and the
American Nuclear Society (ANS) in 1995, it is called the ANSI/ANS 10.3-1995
Standard for Documentation of Computer Software. The standard provides a
flexible, robust framework for documentation needs. One of its goals is to
encourage better communication between developer and user and to facilitate
effective selection, usage, transfer, conversion and modification of computer
software. The standard is not a rigid set of specifications but a guide that can
apply to most software projects intended for internal or external use. While the
standard cannot cover all documentation problems, it is a good starting point,
even for the most complex software. Similarly, while the standard provides
recommendations for documenting scientific and engineering software, it
doesn't offer guidance for online monitoring, control or safety systems, and
doesn't specifically address the unique requirements of consumer-
oriented software.
Bill Brykczynski [6]
According to author software documentation can be considered as one of the
checklist for inspection of software.
Janicki, Ryszard, David L.
Parnas, and Jeffery Zucker
[13]
They describe the use of relations (represented as tables) as a means of
documenting the requirements and behaviour of software. Their work highlights
two key limitations to current documentation practices. They also state, that
documentation continues to be inadequate due to the vagueness and imprecision
of natural languages. These individuals believe that even the best software
documentation is unclear. Further they, suggest that the limitation in natural
languages is a primary cause of informal documentation. They further add that
this informality of the documentation in turn cannot be systematically analysed,
resulting in inconsistent and incomplete information. They also present a
solution to building consistent and complete documentation by describing
software using tabular mathematical relationships.
Tilley Scott [25]
The author comments on the deficiencies of traditional software documentation
techniques. The author also notes that it is extremely inefficient to break down
communication into units so that anyone can
Understand them.
IV. CONCLUSION
Thus we conclude that documentation is considered as an
essential instrument since it conveys meaningful and
functional information related to software.
REFERENCES
[1] Andrew Forward, Timothy Lethbridge, “The relevance of
software documentation, tools and technologies: a survey”,
Proceedings of the 2002 ACM Symposium on Document
Engineering, November, 8-09-2002.
[2] Andrew J. Forward, Timothy, “Qualities of Relevant Software
Documentation: An Industrial Study”, available from psu.edu.
[3] Andrew J. Forward, “Software Documentation Building and
Maintaining Artefacts of Communication”, presented to the
Faculty of Graduate and Postdoctoral Studies in partial
fulfilment of the requirements for the degree Master in Computer
Science, Ottawa Carleton Institute of Computer Science,
University of Ottawa, Canada, 2002.
[4] Antoniol, G. , Canfora, G. , De Lucia, A. and Merlo, E.,
“Recovering code to documentation links in OO systems”,
Published in: Reverse Engineering, 1999. Proceedings. Sixth
Working Conference on 6 8 October 1999, pages 136 144,
ISBN 07695 0303 9.
[5] Barker. T. T, “Software documentation: from instruction to
integration”, Published in: Professional Communication, IEEE
Transactions on (Volume: 33, Issue: 4), pages 172 177, ISSN
0361 1434, 1990.
[6] Bill Brykczynski, “A Survey of Software Inspection Checklists”,
ACM SIGSOFT, Software Engineering Notes, volume 24 no 1,
January 1999, Page 82.
[7] Briand. L. C, “Software documentation: how much is enough?”
Published in: Software Maintenance and Reengineering, 2003.
Proceedings, Seventh European Conference on 26 28 March
2003, pages 13 15, ISSN 1534 5351.
[8] Chapin, Ned, “Trends in Preserving and Enhancing the Value of
Software”, International Conference on Software Maintenance
(ICSM'00), 11-14 October 2000, San Jose, California, USA,
Proceedings. IEEE Computer Society, 2000.
[9] Curtis R. Cook, Marcello Visconti, “NEW AND IMPROVED
DOCUMENTATION PROCESS MODEL”, Proceedings of the
14th Pacific Northwest Software Quality Conference, 1996.
[10] Curtis, Bill, Herb Krasner, and Neil Isco, A Field Study of the
Software Design Process for Large Systems”, Communications
of the ACM 31(11):1268-1287, November, 1988.
[11] Hunt, Andrew and David Thomas, The Pragmatic
Programmer”, Addison Wesley Longman, Inc. 2000.
[12] Ian Sommerville, Software Documentation, Lancaster
University, UK Issue 3, August 2000.
[13] Janicki, Ryszard, David L. Parnas, and Jeffery Zucker, Tabular
representations in relational documents”, In C. Brink, editor,
Relational Methods in Computer Science. Springer-Verlag,
1996.
[14] June S. Hopkins and Jean M. Jeroow, “Documenting The
Software Development Process” , 1990 ACM 0 - 89791- 414 -
7/90/1000 0125
Copyright © 2014 IJEIR, All right reserved
416
International Journal of Engineering Innovation & Research
Volume 3, Issue 4, ISSN: 2277 5668
[15] Kari Laitinen, “Document Classification for Software Quality
Systems”, Technical Research Centre of Finland (VTT)
Computer Technology Laboratory, ACM SIGSOFT Software
Engineering Notes vol 17 no 4 Oct 1992 Page 32
[16] Klare, George R, “Readable computer documentation”, p148
167, ACM JCD, Volume 24,Communications of the ACM
31(11):1268-1287, November, 1988.
[17] Lethbridge, T.C., Singer, J. and Forward, A., “How software
engineers use documentation: the state of the practice”,
published in Frontiers of Software Engineering, volume 20, issue
6, ISSN 0740 7459, 2003.
[18] Nasution. M.F.F, Weistroffer. H.R, “Documentation in Systems
Development: A Significant Criterion for Project Success”,
Published in: System Sciences, 2009. HICSS '09. 42nd Hawaii
International Conference on 5 9 January 2009, pages 1 9,
ISBN 978 07695 34503.
[19] Parnas, D.L. ; Univ. of Limerick, Limerick ; Vilkomir, S.A.,
“Precise Documentation of Critical Software”, Published in:
High Assurance Systems Engineering Symposium, 2007. HASE
'07. 10th IEEE, pages 237 244, ISSN 1530 2059.
[20] Qian Hu , “Software documentation writing on the project of
software upgrade and maintenance”, 2012, International
Conference, page 1400 1403, ISBN 978 14673 14107,
publisher IEEE.
[21] Remo. C. Boer, Hans van Vliet, “Writing and Reading Software
Documentation: How the development process may affect
understanding, “, published in Cooperative and Human Aspects
on Software Engineering, 2009. CHASE '09. ICSE, pages 40
47, ISBN 978 - 1 - 4244.
[22] Scheff, Benson H. and Tom Georgon., Letting software
engineers do software engineering or freeing software engineers
from the shackles of documentation”, p81 – 91, SIGDOC '88,
Ann Arbor, Michigan, USA, ACM Press, 1988.
[23] Sulaiman. S, Sahibudding. S “Production and maintenance of
system documentation: what, why, when and how tools should
support the practice”, Published in: Software Engineering
Conference, 2002. Ninth Asia-Pacific, pages 558 5667, ISSN
1530 1362.
[24] Thomas, Bill, Dennis Smith and Scott Tilley, Documentation
for software engineers: what is needed to aid system
understanding?”, p 235 236, SIGDOC '01, Sante Fe, New
Mexico,
[25] Tilley Scott, “Documenting-in-the-large vs. documenting-in-the-
small”. In Proceedings of the 1993 IBM/NRC CAS Conference
(CASCON '93), (Toronto, Ontario; October 25-28, 1993), pages
1083--1090, October 1993.
[26] Vikas S. Chomal, Dr. Jatinderkumar R. Saini, ”Identification and
Analysis of Causes for Software Failures”, NATIONAL
JOURNAL OF COMPUTER SCIENCE AND TECHNOLOGY]
Volume: 04 | Issue: 02 | July December 2012
[27] Vikas S. Chomal, Dr. Jatinderkumar R. Saini, ”Software Quality
Improvement by Documentation Knowledge Management
Model”, National Journal of System And Information
Technology, Volume 6, Number 1, June 2013, ISSN : 0974
3308, Page Number: 49 68
[28] Vikas S. Chomal, Dr. Jatinderkumar R. Saini, ”Finding Trend of
Both Frequency and Type of Errors from Software Project
Documentation”, International Journal of Emerging Trends &
Technology in Computer Science (IJETTCS), Volume 2, Issue 5,
September October 2013 ISSN 2278-6856
[29] Vikas S. Chomal, Dr. Jatinderkumar R. Saini, “Software
Template to Improve Quality of Database Design on basis of
Error Identification from Software Project Documentation”,
International Journal of Engineering and Management Research,
Volume-4, Issue-1, February-2014, ISSN No.: 2250-0758, Page
Number: 168-179
[30] Vikas S. Chomal, Dr. Jatinderkumar R. Saini, “ Cataloguing
Most Severe Causes that lead Software Projects to Fail”,
International Journal on Recent and Innovation Trends in
Computing and Communication , May 2014 ISSN: 2321-8169
Volume: 2 Issue: 5 pages 11431147
[31] Vir Phoha, “A standard for software documentation”, published
in Computer Science and Information Processing, volume 30,
issue 10, pages 97-98, ISSN: 0018-9162, publisher - IEEE.
[32] Visconti. M, Cook C. R, “An overview of industrial software
documentation practice”, Published in: Computer Science
Society, 2002. SCCC 2002. Proceedings. 22nd International
Conference of the Chilean, pages 179 186, ISSN 1522
4902.
[33] Walters, N.J, Beck, C.E., “A discourse analysis of software
documentation: implications for the profession”, Published in:
Professional Communication, IEEE Transactions on (Volume:
35 , Issue: 3 ), pages 156 167, ISSN 0361 1434, 1992.
[34] Young F. H, “Software engineering and software documentation:
a unified long course”, published in Frontiers in Education
Conference, 1991. Twenty-First Annual Conferences.
'Engineering Education in a New World Order.' Proceedings.
Pages 593 595, ISBN 07803 0222 2.
... Any communicable material, including text, audio, video, CDs, and DVDs, as well as their combinations, may be used as documentation to define certain features of a product, system, or process. In the information age of today, the term is widely used to refer to engineering or software documentation, which typically includes printed books or computer-readable files that describe the components and structure or, alternatively, the functionality of a system or product [67]. The importance of documentation cannot be overstated because decisions about individual lives, organizations and businesses, and governments at all levels are made today and will be made in the future based on the understanding (or lack thereof) of the past. ...
... This section of the study is conceptually and contextually based on one of the areas that the subject matter of documentation has been well applied, as discussed above. It is the software documentation aspect; it is made up of process and product documentation [67]. Documents that detail the creation and upkeep of a system are referred to as process documentation. ...
... The product that is being created is described in the product documentation. User documentation provides a product description that is focused on system users, as opposed to system documentation, which defines the product from the perspective of the engineers creating and maintaining the system [67,68]. Figure 2 gives an illustrated view on the phenomenon. ...
Article
Full-text available
The COVID-19 pandemic that recently broke forth revealed the waning state of a considerable number of healthcare facilities, especially in unindustrialized territories. This is of great concern, and it has become pertinent to identify determinants of efficient maintenance management in developing countries. There is an inefficient maintenance management of hospital buildings due to a low level of maintenance documentation, which otherwise would have facilitated the adoption of digital twin (DT) technology. The existing maintenance management frameworks and models have not explored and evaluated maintenance documentation as an all-inclusive construct. Hence, this study was aimed at emphasizing the significance of maintenance documentation for its adoption as one of the main determinants of efficient maintenance management, with a view to attaining the DT maintenance management of hospital buildings in Nigeria. After a theoretical review on existing studies around documentation, the software documentation concept was used to conceptualise this observed gap in maintenance management models for public hospital buildings in developing countries. This critical review, which forms part of an ongoing study, asserts that maintenance documentation is a major construct for efficient maintenance management and a prerequisite for the adoption of DT in the management of healthcare constructed facilities in developing countries.
... quality is one of the factors leading to better overall software quality (Gorla and Lin, 2010;Chomal and Saini, 2014). Moreover, while R is commonly used for scientific software, 'how a behaviour is implemented' is scarcely sought, according to the survey. ...
Article
R is a package-based programming ecosystem that provides an easy way to install third-party code, datasets, and examples. Thus, R developers rely heavily on the documentation of the packages they import to use them correctly and accurately. This documentation is often written using Roxygen, equivalent to Java’s well-known Javadoc. This two-part study provides the first analysis in this area. First, 379 systematically-selected, open-source R packages were mined and analysed to address the quality of their documentation in terms of presence, distribution, and completeness to identify potential sources of documentation debt of technical debt that describes problems in the documentation. Second, a survey addressed how R package developers perceive documentation and face its challenges (with a response rate of 10.04%). Results show that incomplete documentation is the most common smell, with several cases of incorrect use of the Roxygen utilities. Unlike in traditional API documentation, developers do not focus on how behaviour is implemented but on common use cases and parameter documentation. Respondents considered the examples section the most useful, and commonly perceived challenges were unexplained examples, ambiguity, incompleteness and fragmented information.
... Sangeetha and Dalal [6] articulate that effort estimation and distribution is a critical activity and to be considered in each and every phase of software development whether it is planning for development or monitoring the development process of software or may be delivering the software. Researchers have also presented a detailed analysis of the various reasons responsible for failure of software [15] [16], improvements in the quality of the software [17] and database [18] developed through the documentation of the process of development of software [19] and importance of deciding priorities during requirements analysis [20]. Rosa et al. [23] presents a set of effort and schedule estimation relationships for predicting software development. ...
Research
Full-text available
: Effort distribution in software engineering is a well-known term used to measure cost and effort estimation for each and every phase or activity in software development. Effort distribution is taken in consideration in almost all IT companies while developing software. But it is mostly not considered or overlooked in developing academic software projects by students of computer science courses. The paper presents with results of an experimentation on phase effort distribution data of 84 software academic projects of post graduate final year students of computer science. The phase effort distribution provided by students were collected, analyzed and compared with COCOMO II model which provides effort distribution required in software development. Finally, this paper also discusses and provides recommendation about the use and importance of effort distribution in academic software projects development.
... 13 [13] [14] Documentations is the process of collecting, organizing, storing and maintaining historical record of programs and other documents used or prepared during the different phases of the life cycle of the software. 14 [15] [16] The effectiveness of documentation within a development process is determined by the way in which the intentions of the authors correspond to the expectations of the potential readers. In a typical software development process, many different kinds of documents are produced and consumed at various points in time. ...
Article
Software documentation is a critical attribute of both software projects and software engineering in general. Documentation is considered as a media of communication among the parties involved during software development as well the one who will be using the software. It consists of written particulars concerning software specifications as well as what it does, in which manner it accomplishes the specified details and even how to exercise it. In this paper, we tried to focus on the role of documentation in software projects.
... Also they categorize the techniques from a user's perspective according to five criteria such as ease of use, total time taken, scalability, accuracy, and total number of comparisons required to make decisions. Further, Chomal and Saini [36,40] states that requirement prioritization and freezing are to be considered as an essential task during requirement analysis process so that the developed software has a high probability of acceptance from customer's side. ...
Conference Paper
Full-text available
Software development projects are a crucial component of computer science courses. They provide students a platform were they shape theoretical knowledge into technical aspects. During this development phase students need to prioritization the requirements within a stipulated time. There are many requirements prioritization techniques available and deciding the most suitable one is primarily the important task. Prioritization techniques such as Simple Ranking, Numerical Assignment Technique, Cumulative Voting, Analytical Hierarchical Process, Value Oriented Prioritization, Binary Search Tree and Bubble Sort were considered for the research purpose. We prepared a list of six parameters which were used to assign score to these prioritization techniques. The main objective behind scoring these techniques was to indicate that which technique is more suitable for software projects carried out by post graduate courses in computer science. The result from the experiment shows that Numerical Assignment Technique (NAT) is supposed to be the best method for prioritizing software requirements considering software development in academic environment.
... They also endeavour to make clear that existing techniques are not providing sufficient automation for such systems due to their certain limitations. Chomal and Saini [36,37,38] measured requirement as one of the quantifiable attribute which is used as a criterion to evaluate and score software project documentation. ...
Article
Full-text available
Software requirement is a state or an aptitude necessitated by end user to overcome a problem or to accomplish the needed purpose. Further, it is generally classified into functional and non – functional requirements. Considering this, a well premeditated course of action is used for determining user potential for a new as well as existing product, which is known as Requirement Engineering or Requirement Analysis. Also it is considered as one of the most significant task and serves as a foundation in software development. Requirement analysis procedure consists of various activities such as understanding of domain, collection and classification of requirements, conflict resolution, requirements prioritization and validation. Through this paper, we describe the reviews of requirements engineering and essentially on the most noteworthy task that is prioritizing and freezing of software requirements during Requirement analysis process. The paper is divided into four sections; first section is introductory, followed by literature review. Section three represents finding and analysis from literature review, followed by concluding section.
... They also endeavour to make clear that existing techniques are not providing sufficient automation for such systems due to their certain limitations. Chomal and Saini [36, 37, 38] measured requirement as one of the quantifiable attribute which is used as a criterion to evaluate and score software project documentation. ...
Research
Software requirement is a state or an aptitude necessitated by end user to overcome a problem or to accomplish the needed purpose. Further, it is generally classified into functional and non – functional requirements. Considering this, a well premeditated course of action is used for determining user potential for a new as well as existing product, which is known as Requirement Engineering or Requirement Analysis.
... 13 [13] [14] Documentations is the process of collecting, organizing, storing and maintaining historical record of programs and other documents used or prepared during the different phases of the life cycle of the software. 14 [15] [16] The effectiveness of documentation within a development process is determined by the way in which the intentions of the authors correspond to the expectations of the potential readers. In a typical software development process, many different kinds of documents are produced and consumed at various points in time. ...
Article
Full-text available
Software documentation is a critical attribute of both software projects and software engineering in general. Documentation is considered as a media of communication among the parties involved during software development as well the one who will be using the software. It consists of written particulars concerning software specifications as well as what it does, in which manner it accomplishes the specified details and even how to exercise it. In this paper, we tried to focus on the role of documentation in software projects.
Conference Paper
Past generations of software developers were well on the way to building a software engineering mindset/gestalt, preferring tools and techniques that concentrated on safety, security, reliability, and code re-usability. Computing education reflected these priorities and was, to a great extent organized around these themes, providing beginning software developers a basis for professional practice. In more recent times, economic and deadline pressures and the de-professionalism of practitioners have combined to drive a development agenda that retains little respect for quality considerations. As a result, we are now deep into a new and severe software crisis. Scarcely a day passes without news of either a debilitating data or website hack, or the failure of a mega-software project. Vendors, individual developers, and possibly educators can anticipate an equally destructive flood of malpractice litigation, for the argument that they systematically and recklessly ignored known best development practice of long standing is irrefutable. Yet we continue to instruct using methods and to employ development tools we know, or ought to know, are inherently insecure, unreliable, and unsafe, and that produce software of like ilk. The authors call for a renewed professional and educational focus on software quality, focusing on redesigned tools that enable and encourage known best practice, combined with reformed educational practices that emphasize writing human readable, safe, secure, and reliable software. Practitioners can only deploy sound management techniques, appropriate tool choice, and best practice development methodologies such as thorough planning and specification, scope management, factorization, modularity, safety, appropriate team and testing strategies, if those ideas and techniques are embedded in the curriculum from the beginning. The authors have instantiated their ideas in the form of their highly disciplined new version of Niklaus Wirth's 1980s Modula-2 programming notation under the working moniker Modula-2 R10. They are now working on an implementation that will be released under a liberal open source license in the hope that it will assist in reforming the CS curriculum around a best practices core so as to empower would-be professionals with the intellectual and practical mindset to begin resolving the software crisis. They acknowledge there is no single software engineering silver bullet, but assert that professional techniques can be inculcated throughout a student's four-year university tenure, and if implemented in the workplace, these can greatly reduce the likelihood of multiplied IT failures at the hands of our graduates. The authors maintain that professional excellence is a necessary mindset, a habit of self-discipline that must be intentionally embedded in all aspects of one's education, and subsequently drive all aspects of one's practice, including, but by no means limited to, the choice and use of programming tools.
Article
Full-text available
Software failures account to nearly 80% of all the softwares developed. This paper presents an identification of the causes that lead a software to fail. We have surveyed the related literature and attempted to present an extensive and comprehensive list of the various reasons responsible for making a software unusable. It has been found that the softwares fail due to shortened requirements, deficient of user involvement, lack of resources, impractical expectations, short of executive support, altering requirements specifications, etc. The paper also presents an analysis as well as categorization of the identified causes.
Article
Full-text available
Software development projects are an indispensable constituent of computer science courses. They offer the prospects for students to apply theoretical material and to expand valuable knowledge in an environment typical of the workplace. This paper deals with a vital and noteworthy concern in the development of computer software-its quality. The software systems which students as well as professional software engineers design are increasing in complexity, and it is often away from human ability to confirm their correctness. These benefits, however, are difficult to realise. In particular, we provide a software template for software engineering projects through which quality of students software project can be improved. The software template been designed can find out various errors committed by the students while developing their software projects in any of the following areas – database, designing, reports, testing, exceptions handling and so on. Software template also further provides necessary assistance in order to get rid of these errors and thus improving the quality of the software project. We consider our template will be a useful tool in indentifying errors in student's software project and to eliminate these errors and hence improving the quality. The paper presents and discusses about software template that has been developed and how it can be incorporated to access the quality of software projects developed by the students.
Article
Full-text available
This paper describes an innovative study undertaken for software projects carried out for post graduate course in computer science. Today software system is a fundamental part of each and every business model, be it core product manufacturing, banking, healthcare, insurance, aviation, hospitality, social networking, shopping, e-commerce, education or any other domain. Therefore, considering this criteria, the main aim of software project that is been carried out by final year students it to give students exposure to the realities of global software development. Though the software industry has advanced quiet a lot in past decade, however percentage of software failure has also increased, which led to the loss of capital, time, goodwill , loss of information and so on and. Software could fail due to faults introduced in various stages of software or product development life cycle starting from project initiation until deployment. The specific focus of this paper is to uncover various types of errors done by students during software development, which is been carried out as a part of their master degree programme.
Article
Full-text available
Nowadays software system is a vital constituent of each and every business representation, be it core product manufacturing, banking, healthcare, insurance, aviation, hospitality, social networking, shopping, e-commerce, education or any other sphere. If any business has to be leveraged and shorten then software has to be integrated with the main stream business of any organization. Crafty and development of any software system entails massive capital, a lot of time, intellectual, domain expertise, tools and infrastructure. Despite the fact that the software industry has highly developed quiet a lot in past decade, however percentage of software failure has also enlarged, which led to the loss of capital, time, good-will, loss of information and in some cases severe failures of critical applications also lead to the loss of lives. This paper presents a classification of the grounds that leads software to be unsuccessful. We have surveyed the allied literature and endeavour to present an extensive and ample catalogue of the diverse causes accountable for making software out of order. The paper also presents a scrutiny as well as categorization of the identified causes.
Conference Paper
Full-text available
The effectiveness of documentation within a development process is determined by the way in which the intentions of the authors correspond to the expectations of the potential readers. Ideally, the members of a development team share a certain understanding of (the role of) the different types of documentation. However, since one's expectations of a document are personal, and part of a tacitly formed mental model, we can expect different levels of shared understanding between different development team members. We elicited and analyzed the mental models of software documentation from eight members of a single development team. We found indeed different levels of shared understanding between different people. To our surprise, the levels of shared understanding within the team appear closely tied to the development process employed. From Conway's law we know that an organization's structure is mirrored in the structure of the software that the organization produces. Our findings suggest that the organization's development process may likewise be mirrored in the extent to which a development team shares a common frame of reference. Hence, the development process followed may have implications for the effectiveness with which development knowledge can be shared through software documentation.
Article
The Software Engineering Process Group (SEPG) at the Data Systems Division of Litton Systems, Inc., was given the task of documenting the software development process used within the division. This paper describes how the SEPG at Litton accomplished this task. It discusses the sources we used for guidance and describes the resulting documentation for defining the software development process and the methods and tools that support the process. After reviewing the existing software process documentation at Litton, the SEPG concluded that three separate documents were required: a revised set of Software Policies and Procedures (PPGs), a Software Engineering Handbook, and a Software Management Handbook. The SEPG established working groups to develop these documents. The working group responsible for the Software Engineering Handbook decided to develop it as a user manual for the software development process. Following Weiss' guidelines for developing a usable user manual, the working group developed storyboards for sections of the manual. A model initially developed at IBM and refined by SEI and others was used to describe the software development process as a series of work tasks, each of which has entry criteria, exit criteria, objectives, and steps to perform. Several authors developed the storyboards and the corresponding modules of the handbook. The handbook was partitioned into short modules, each of which has a topic sentence and a figure (where applicable). The result is a modular Software Engineering Handbook that is easy to read and maintain. The use of working groups and the development of the Software Engineering Handbook as a user manual proved to be efficient and effective methods for generating high quality software process documentation.
Conference Paper
The software documentation is unpopular among many developers at present while the documents are important for the staffs who work for secondary development and software maintenance. For this phenomenon, a teaching method of writing software documentation is proposed in this paper, in which the software maintenance is the driving force to make students fully understand and grasp the method of software documentation writing through an upgrade and maintenance software project. And students learn to write effective software documentation to establish the level and structure of the document.
Article
Software inspection processes call for a checklist to provide reviewers with hints and recommendations for finding defects during the examination of a workproduct. Many checklists have been published since Michael Fagan created the inspection process in the mid-1970's. This paper surveys 117 checklists from 24 sources. Different categories of checklist items are discussed and examples are provided of good checklist items as well as those that should be avoided.