SOFTWARE DOCUMENTATION____________________________________________________________

Software documentation is written text that accompanies

computer software. It either explains how the software operates or
how to use it, although it may mean different things to people in
different roles.

Documentation is an important part of software engineering. Types

of documentation include:

1. Requirements - Statements that identify attributes,

capabilities, characteristics, or qualities of a system. This is
the foundation for what shall be or has been implemented.
2. Architecture/Design - Overview of software. This includes
relations to an environment and construction principles to
be used in the design of software components.
3. Technical - Documentation of code, algorithms, interfaces,
and APIs.
4. End user - Manuals for the end-user, system administrators
and support staff.
5. Marketing - How to market the product and analysis of the
market demand.

Requirements documentation

Requirements documentation is the description of what a particular

software does or shall do. It is used throughout the development to
communicate what the software does or shall do. It is also used as
an agreement or as the foundation for agreement on what the
software shall do. Requirements are produced and consumed by
everyone involved in the production of software: end users,
customers, product managers, project managers, sales, marketing,
software architects, usability engineers, interaction designers,
developers, and testers, to name a few. Thus, requirements
documentation has many different purposes.

Requirements come in a variety of styles, notations and formality.

Requirements can be goal-like (e.g., distributed work
environment), close to design (e.g., builds can be started by right-
clicking a configuration file and select the 'build' function), and
anything in between. They can be specified as statements in natural
language, as drawn figures, as detailed mathematical formulas, and
as a combination of them all.

The variation and complexity of requirements documentation

makes it a proven challenge. Requirements may be implicit and
hard to uncover. It is difficult to know exactly how much and what
kind of documentation is needed and how much can be left to the

1
INTRO TO SOFTWARE ENGINEERING
SOFTWARE DOCUMENTATION____________________________________________________________

architecture and design documentation. It is also difficult to know

how to document requirements, considering the variety of people
who shall read and use the documentation. Thus, requirements
documentation is often incomplete (or non-existent). Without
proper requirements documentation, software changes become
more difficult — and therefore more error prone (decreased
software quality) and time-consuming (expensive).

The need for requirements documentation is typically related to the

complexity of the product, the impact of the product, and the life
expectancy of the software. If the software is very complex or
developed by many people (e.g., mobile phone software),
requirements can help to better communicate what to achieve. If
the software is safety-critical and can have negative impact on
human life (e.g., nuclear power systems, medical equipment), more
formal requirements documentation is often required. If the
software is expected to live for only a month or two (e.g., very
small mobile phone applications developed specifically for a
certain campaign) very little requirements documentation may be
needed. If the software is a first release that is later built upon,
requirements documentation is very helpful when managing the
change of the software and verifying that nothing has been broken
in the software when it is modified.

Architecture/Design documentation

Architecture documentation (also known as software architecture

description) is a special breed of design document. In a way,
architecture documents are third derivative from the code (design
document being second derivative, and code documents being
first). Very little in the architecture documents is specific to the
code itself. These documents do not describe how to program a
particular routine, or even why that particular routine exists in the
form that it does, but instead merely lays out the general
requirements that would motivate the existence of such a routine.
A good architecture document is short on details but thick in
explanation. It may suggest approaches for lower level design, but
leave the actual exploration trade studies to other documents.

Another breed of design docs is the comparison document, or trade

study. This would often take the form of a whitepaper. It focuses
on one specific aspect of the system and suggests alternate
approaches. It could be at the user interface, code, design, or even
architectural level. It will outline what the situation is, describe one
or more alternatives, and enumerate the pros and cons of each. A
good trade study document is heavy on research, expresses its idea

2
INTRO TO SOFTWARE ENGINEERING
SOFTWARE DOCUMENTATION____________________________________________________________

clearly (without relying heavily on obtuse jargon to dazzle the

reader), and most importantly, is impartial. It should honestly and
clearly explain the costs of whatever solution it offers as best. The
objective of a trade study is to devise the best solution, rather than
to push a particular point of view. It is perfectly acceptable to state
no conclusion, or to conclude that none of the alternatives are
sufficiently better than the baseline to warrant a change. It should
be approached as a scientific endeavor, not as a marketing
technique.

A very important part of the design document in enterprise

software development is the Database Design Document (DDD). It
contains Conceptual, Logical, and Physical Design Elements. The
DDD includes the formal information that the people who interact
with the database need. The purpose of preparing it is to create a
common source to be used by all players within the scene. The
potential users are:

 Database designer
 Database developer
 Database administrator
 Application designer
 Application developer

When talking about Relational Database Systems, the document

should include following parts:

 Entity - Relationship Schema (enhanced or not),

including following information and their clear
definitions:
o Entity Sets and their attributes
o Relationships and their attributes
o Candidate keys for each entity set
o Attribute and Tuple based constraints

 Relational Schema, including following information:

o Tables, Attributes, and their properties
o Views
o Constraints such as primary keys, foreign keys,
o Cardinality of referential constraints
o Cascading Policy for referential constraints
o Primary keys

It is very important to include all information that is to be used by

all actors in the scene. It is also very important to update the
documents as any change occurs in the database as well.

3
INTRO TO SOFTWARE ENGINEERING
SOFTWARE DOCUMENTATION____________________________________________________________

Technical documentation

It is important for the code documents associated with the source

code (which may include README files and API documentation)
to be thorough, but not so verbose that it becomes overly time-
consuming or difficult to maintain them. Various how-to and
overview documentation guides are commonly found specific to
the software application or software product being documented by
API writers. This documentation may be used by developers,
testers, and also the end-users using the software application.
Today, a lot of high-end applications in the field of power, energy,
transportation, networks, aerospace, safety, security, industry
automation and a variety of other domains are seen. Technical
documentation has become important within such organizations as
the basic and advanced level of information may change over a
period of time with architecture changes.

Code documents are often organized into a reference guide style,

allowing a programmer to quickly look up an arbitrary function or
class.

Technical documentation embedded in source code

Often, tools such as Doxygen, NDoc, javadoc, EiffelStudio,

Sandcastle, ROBODoc, POD, TwinText, or Universal Report can
be used to auto-generate the code documents—that is, they extract
the comments and software contracts, where available, from the
source code and create reference manuals in such forms as text or
HTML files.

The idea of auto-generating documentation is attractive to

programmers for various reasons. For example, because it is
extracted from the source code itself (for example, through
comments), the programmer can write it while referring to the
code, and use the same tools used to create the source code to
make the documentation. This makes it much easier to keep the
documentation up-to-date.

Of course, a downside is that only programmers can edit this kind

of documentation, and it depends on them to refresh the output (for
example, by running a cron job to update the documents nightly).
Some would characterize this as a pro rather than a con.

4
INTRO TO SOFTWARE ENGINEERING
SOFTWARE DOCUMENTATION____________________________________________________________

Literate programming

Respected computer scientist Donald Knuth has noted that

documentation can be a very difficult afterthought process and has
advocated literate programming, written at the same time and
location as the source code and extracted by automatic means. The
programming languages Haskell and CoffeeScript have built-in
support for a simple form of literate programming, but this support
is not widely used.

Elucidative programming

Elucidative Programming is the result of practical applications of

Literate Programming in real programming contexts. The
Elucidative paradigm proposes that source code and
documentation be stored separately. This paradigm was inspired by
the same experimental findings that produced Kelp.

Often, software developers need to be able to create and access

information that is not going to be part of the source file itself.
Such annotations are usually part of several software development
activities, such as code walks and porting, where third party source
code is analyzed in a functional way. Annotations can therefore
help the developer during any stage of software development
where a formal documentation system would hinder progress. Kelp
stores annotations in separate files, linking the information to the
source code dynamically.

User documentation

Unlike code documents, user documents simply describe how a

program is used.

In the case of a software library, the code documents and user

documents could, in some cases, be effectively equivalent and
worth conjoining, but for a general application, this is not often
true.

Typically, the user documentation describes each feature of the

program, and assists the user in realizing these features. A good
user document can also go so far as to provide thorough
troubleshooting assistance. It is very important for user documents
to not be confusing, and for them to be up to date. User documents
need not be organized in any particular way, but it is very
important for them to have a thorough index. Consistency and
simplicity are also very valuable. User documentation is

5
INTRO TO SOFTWARE ENGINEERING
SOFTWARE DOCUMENTATION____________________________________________________________

considered to constitute a contract specifying what the software

will do. API Writers are very well accomplished towards writing
good user documents as they would be well aware of the software
architecture and programming techniques used. See also technical
writing.

There are three broad ways in which user documentation can be

organized.

1. Tutorial

A tutorial approach is considered the most useful

for a new user, in which they are guided through
each step of accomplishing particular tasks.[1]

2. Thematic

A thematic approach, where chapters or sections

concentrate on one particular area of interest, is of
more general use to an intermediate user. Some
authors prefer to convey their ideas through a
knowledge based article to facilitate the user needs.
This approach is usually practiced by a dynamic
industry, such as Information Technology, where
the user population is largely correlated with the
troubleshooting demands [2]

3. List or Reference

The final type of organizing principle is one in

which commands or tasks are simply listed
alphabetically or logically grouped, often via cross-
referenced indexes. This latter approach is of
greater use to advanced users who know exactly
what sort of information they are looking for.

A common complaint among users regarding software

documentation is that only one of these three approaches was taken
to the near-exclusion of the other two. It is common to limit
provided software documentation for personal computers to online
help that give only reference information on commands or menu
items. The job of tutoring new users or helping more experienced
users get the most out of a program is left to private publishers,
who are often given significant assistance by the software
developer.

6
INTRO TO SOFTWARE ENGINEERING
SOFTWARE DOCUMENTATION____________________________________________________________

Composing user documentation

Like other forms of technical documentation, good user

documentation benefits from an organized process of development.
In the case of user documentation, the process as it commonly
occurs in industry consists of five steps

1. User analysis, the basic research phase of the process

2. Planning, or the actual documentation phase.
3. Draft review, a self-explanatory phase where feedback
is sought on the draft composed in the previous step.
4. Usability testing, whereby the usability of the document
is tested empirically.
5. Editing, the final step in which the information collected
in steps three and four is used to produce the final draft.

Documentation and agile development controversy

"The resistance to documentation among developers is well known

and needs no emphasis." This situation is particularly ambivalent
in agile software development because these methodologies try to
avoid any unnecessary activities that do not directly bring value.
Specifically, the Agile Manifesto advocates valuing "working
software over comprehensive documentation", which could be
interpreted cynically as "We want to spend all our time coding.
Remember, real programmers don't write documentation."

A survey among software engineering experts revealed, however,

that documentation is by no means considered unnecessary in agile
development. Yet it is acknowledged that there are motivational
problems in development, and that documentation methods tailored
to agile development (e.g. through Reputation systems and
Gamification) may be needed.

Marketing documentation

For many applications it is necessary to have some promotional

materials to encourage casual observers to spend more time
learning about the product. This form of documentation has three
purposes:-

1. To excite the potential user about the product and instill in

them a desire for becoming more involved with it.
2. To inform them about what exactly the product does, so
that their expectations are in line with what they will be
receiving.

7
INTRO TO SOFTWARE ENGINEERING
SOFTWARE DOCUMENTATION____________________________________________________________

3. To explain the position of this product with respect to other

alternatives.

8
INTRO TO SOFTWARE ENGINEERING