Software documentation

related topics
{system, computer, user}
{theory, work, human}
{math, number, function}
{work, book, publish}
{company, market, business}
{law, state, case}
{specie, animal, plant}

Software documentation or source code documentation is written text that accompanies computer software. It either explains how it operates or how to use it, and may mean different things to people in different roles.

Contents

Involvement of people in software life

Documentation is an important part of software engineering. Types of documentation include:

Requirements documentation

Requirements documentation is the description of what a particular software does or shall do. It is used throughout 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 architecture and design documentation, and it is difficult to know how to document requirements considering the variety of people that 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).

Full article ▸

related documents
Interactive art
Short-term memory
Learning object
Garbage In, Garbage Out
System dynamics
RTFM
Music technology
Gerald Jay Sussman
Subsumption architecture
Not Invented Here
Shovelware
Z3 (computer)
VRML
Usability testing
SHRDLU
SAPHIRE
Open system (computing)
CHS conversion
Editor war
G.711
Time to live
Display PostScript
IBM 704
Fluent, Inc.
Phil Katz
Program counter
Fiber distributed data interface
Karplus-Strong string synthesis
UserLand Software
Fault tree analysis