Software documentation
Encyclopedia
Software documentation or source code documentation is written text that accompanies computer
Computer
A computer is a programmable machine designed to sequentially and automatically carry out a sequence of arithmetic or logical operations. The particular sequence of operations can be changed readily, allowing the computer to solve more than one kind of problem...

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

Role of documentation in software development

Documentation
Documentation
Documentation is a term used in several different ways. Generally, documentation refers to the process of providing evidence.Modules of Documentation are Helpful...

 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. Includes relations to an environment and construction principles to be used in 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 development
Software development
Software development is the development of a software product...

 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, customer
Customer
A customer is usually used to refer to a current or potential buyer or user of the products of an individual or organization, called the supplier, seller, or vendor. This is typically through purchasing or renting goods or services...

s, product manager
Product Manager
A product manager investigates, selects, and develops products for an organization, performing the activities of product management.A product manager considers numerous factors such as intended demographic, the products offered by the competition, and how well the product fits with the company's...

s, project manager
Project manager
A project manager is a professional in the field of project management. Project managers can have the responsibility of the planning, execution, and closing of any project, typically relating to construction industry, architecture, computer networking, telecommunications or software...

s, sales
Sales
A sale is the act of selling a product or service in return for money or other compensation. It is an act of completion of a commercial activity....

, marketing
Marketing
Marketing is the process used to determine what products or services may be of interest to customers, and the strategy to use in sales, communications and business development. It generates the strategy that underlies sales techniques, business communication, and business developments...

, software architect
Software architect
Software architect is a general term with many accepted definitions, which refers to a broad range of roles. Generally accepted terminology and certifications began appearing in connection with this role near the beginning of the 21st century.-History:...

s, usability engineers
Usability engineering
Usability engineering is a field that is concerned generally with human-computer interaction and specifically with making human-computer interfaces that have high usability or user friendliness...

, interaction design
Interaction design
In design, human–computer interaction, and software development, interaction design, often abbreviated IxD, is "the practice of designing interactive digital products, environments, systems, and services." Like many other design fields interaction design also has an interest in form but its main...

ers, developer
Software developer
A software developer is a person concerned with facets of the software development process. Their work includes researching, designing, developing, and testing software. A software developer may take part in design, computer programming, or software project management...

s, and testers
Software testing
Software testing is an investigation conducted to provide stakeholders with information about the quality of the product or service under test. Software testing can also provide an objective, independent view of the software to allow the business to appreciate and understand the risks of software...

, 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
Natural language
In the philosophy of language, a natural language is any language which arises in an unpremeditated fashion as the result of the innate facility for language possessed by the human intellect. A natural language is typically used for communication, and may be spoken, signed, or written...

, 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 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.

Traditionally, requirements are specified in requirements documents (e.g. using word processing applications and spreadsheet applications). To manage the increased complexity and changing nature of requirements documentation (and software documentation in general), database-centric systems and special-purpose requirements management
Requirements management
Requirements management is the process of documenting, analyzing, tracing, prioritizing and agreeing on requirements and then controlling change and communicating to relevant stakeholders. It is a continuous process throughout a project...

 tools are advocated.

Architecture/Design documentation

Architecture documentation is a special breed of design document. In a way, architecture documents are third derivative from the code (design document
Design document
A software design document is a written description of a software product, that a software designer writes in order to give a software development team an overall guidance of the architecture of the software project. An SDD usually accompanies an architecture diagram with pointers to detailed...

 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 on 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
User interface
The user interface, in the industrial design field of human–machine interaction, is the space where interaction between humans and machines occurs. The goal of interaction between a human and a machine at the user interface is effective operation and control of the machine, and feedback from the...

, 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 clearly (without relying heavily on obtuse jargon
Jargon
Jargon is terminology which is especially defined in relationship to a specific activity, profession, group, or event. The philosophe Condillac observed in 1782 that "Every science requires a special language because every science has its own ideas." As a rationalist member of the Enlightenment he...

 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.




  • 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, including following information and their clear definitions:

    • Entity Sets and their attributes
    • Relationships and their attributes
    • Candidate keys for each entity set
    • Attribute and Tuple based constraints


  • Relational Schema, including following information:

    • Tables, Attributes, and their properties
    • Views
    • Constraints such as primary keys, foreign keys,
    • Cardinality of referential constraints
    • Cascading Policy for referential constraints
    • 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.

Technical documentation

This is what most programmer
Programmer
A programmer, computer programmer or coder is someone who writes computer software. The term computer programmer can refer to a specialist in one area of computer programming or to a generalist who writes code for many kinds of software. One who practices or professes a formal approach to...

s mean when using the term software documentation. When creating software, code
Source code
In computer science, source code is text written using the format and syntax of the programming language that it is being written in. Such a language is specially designed to facilitate the work of computer programmers, who specify the actions to be performed by a computer mostly by writing source...

 alone is insufficient. There must be some text along with it to describe various aspects of its intended operation. It is important for the code documents to be thorough, but not so verbose that it becomes difficult to maintain them. Several How-to and overview documentation are found specific to the software application or software product being documented by API Writer
API Writer
An API writer is a technical writer who writes documents that describe an application programming interface . The primary audience includes programmers, developers, system architects, and system designers.- Overview :...

s. This documentation may be used by developers, testers and also the end customers or clients using this software application. Today, we see lot of high end applications in the field of power, energy, transportation, networks, aerospace, safety, security, industry automation and a variety of other domains. 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. Hence, technical documentation has gained lot of importance in recent times, especially in the software field.

Often, tools
Documentation generator
A documentation generator is a programming tool that generates documentation intended for programmers or end users , or both, from a set of specially commented source code files, and in some cases, binary files....

 such as Doxygen
Doxygen
Doxygen is a documentation generator for multiple programming languages.Doxygen is a tool for writing software reference documentation. The documentation is written within code, and is thus relatively easy to keep up to date...

, NDoc
NDoc
NDoc is a code documentation generator for the Common Language Infrastructure. It is licensed under the GNU General Public License.- How it works :...

, javadoc
Javadoc
Javadoc is a documentation generator from Sun Microsystems for generating API documentation in HTML format from Java source code.The "doc comments" format used by Javadoc is the de facto industry standard for documenting Java classes. Some IDEs, such as Netbeans and Eclipse automatically generate...

, EiffelStudio
EiffelStudio
EiffelStudio is a development environment for the Eiffel programming language developed and distributed by Eiffel Software.EiffelStudio includes a combination of tools integrated under a single user interface: compiler, interpreter, debugger, browser, metrics tool, profiler, diagram tool...

, Sandcastle, ROBODoc
ROBODoc
ROBODoc is a documentation tool similar to Javadoc and licensed under the GPL. It is used to extract API documentation from source code. It can be used with any language that supports comments and works by extracting specially formatted headers...

, POD
Plain Old Documentation
Plain Old Documentation, abbreviated pod, is a lightweight markup language used to document the Perl programming language.-Design:pod is designed to be a simple, clean language with just enough syntax to be useful. It purposefully does not include mechanisms for fonts, images, colors or tables...

, TwinText
TwinText
TwinText is a proprietary source code documentation tool. It can generate HTML documents from a variety of programming languages, including C, C++, C#, Java, IDL, PHP, and Visual Basic. It runs on Windows....

, or Universal Report can be used to auto-generate the code documents—that is, they extract the comments and software contracts
Design by contract
Design by contract , also known as programming by contract and design-by-contract programming, is an approach to designing computer software...

, where available, from the source code and create reference manuals in such forms as text or HTML
HTML
HyperText Markup Language is the predominant markup language for web pages. HTML elements are the basic building-blocks of webpages....

 files. Code documents are often organized into a reference guide style, allowing a programmer to quickly look up an arbitrary function or class.

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 comment
Comment (computer programming)
In computer programming, a comment is a programming language construct used to embed programmer-readable annotations in the source code of a computer program. Those annotations are potentially significant to programmers but typically ignorable to compilers and interpreters. Comments are usually...

s), 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.

Donald Knuth
Donald Knuth
Donald Ervin Knuth is a computer scientist and Professor Emeritus at Stanford University.He is the author of the seminal multi-volume work The Art of Computer Programming. Knuth has been called the "father" of the analysis of algorithms...

 has insisted on the fact that documentation can be a very difficult afterthought process and has advocated literate programming
Literate programming
Literate programming is an approach to programming introduced by Donald Knuth as an alternative to the structured programming paradigm of the 1970s....

, writing at the same time and location as the source code
Source code
In computer science, source code is text written using the format and syntax of the programming language that it is being written in. Such a language is specially designed to facilitate the work of computer programmers, who specify the actions to be performed by a computer mostly by writing source...

 and extracted by automatic means.

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 analysed 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 are usually far more diverse with respect to the source code of the program, and instead simply describe how it is used.

In the case of a software library, the code documents and user documents could be effectively equivalent and are 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
Index (publishing)
An index is a list of words or phrases and associated pointers to where useful material relating to that heading can be found in a document...

. Consistency and simplicity are also very valuable. User documentation is considered to constitute a contract specifying what the software will do. API Writer
API Writer
An API writer is a technical writer who writes documents that describe an application programming interface . The primary audience includes programmers, developers, system architects, and system designers.- Overview :...

s 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
Technical writing
Technical writing, a form of technical communication, is a style of writing used in fields as diverse as computer hardware and software, engineering, chemistry, the aerospace industry, robotics, finance, consumer electronics, and biotechnology....

.

There are three broad ways in which user documentation can be organized.
  1. Tutorial: A tutorial
    Tutorial
    A tutorial is one method of transferring knowledge and may be used as a part of a learning process. More interactive and specific than a book or a lecture; a tutorial seeks to teach by example and supply the information to complete a certain task....

     approach is considered the most useful for a new user, in which they are guided through each step of accomplishing particular tasks.
  2. Thematic: A thematic
    Theme (literature)
    A theme is a broad, message, or moral of a story. The message may be about life, society, or human nature. Themes often explore timeless and universal ideas and are almost always implied rather than stated explicitly. Along with plot, character,...

     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 facilitating the user needs. This approach is usually practiced by a dynamic industry, such as Information technology
    Information technology
    Information technology is the acquisition, processing, storage and dissemination of vocal, pictorial, textual and numerical information by a microelectronics-based combination of computing and telecommunications...

    , where the user population is largely correlated with the troubleshooting
    Troubleshooting
    Troubleshooting is a form of problem solving, often applied to repair failed products or processes. It is a logical, systematic search for the source of a problem so that it can be solved, and so the product or process can be made operational again. Troubleshooting is needed to develop and...

     demands
  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 computer
Personal computer
A personal computer is any general-purpose computer whose size, capabilities, and original sales price make it useful for individuals, and which is intended to be operated directly by an end-user with no intervening computer operator...

s to online help
Online help
Online help is topic-oriented, procedural or reference information delivered through computer software. It is a form of user assistance. Most online help is designed to give assistance in the use of a software application or operating system, but can also be used to present information on a broad...

 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.

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.
  3. To explain the position of this product with respect to other alternatives.


One good marketing technique is to provide clear and memorable catch phrases that exemplify the point we wish to convey, and also emphasize the interoperability of the program with anything else provided by the manufacturer.

See also

  • API Writer
    API Writer
    An API writer is a technical writer who writes documents that describe an application programming interface . The primary audience includes programmers, developers, system architects, and system designers.- Overview :...

  • Comparison of documentation generators
  • Design by contract
    Design by contract
    Design by contract , also known as programming by contract and design-by-contract programming, is an approach to designing computer software...

  • Docstring
    Docstring
    In programming, a docstring is a string literal specified in source code that is used, like a comment, to document a specific segment of code. Unlike conventional source code comments, or even specifically formatted comments like Javadoc documentation, docstrings are not stripped from the source...

  • Documentation
    Documentation
    Documentation is a term used in several different ways. Generally, documentation refers to the process of providing evidence.Modules of Documentation are Helpful...

  • User Assistance
    User Assistance
    User assistance is a general term for guided assistance to a user of a software product. The phrase incorporates all forms of help available to a user. Assistance can also automatically perform procedures or step users through the procedure, depending on the question that the user asked...

  • Design document
    Design document
    A software design document is a written description of a software product, that a software designer writes in order to give a software development team an overall guidance of the architecture of the software project. An SDD usually accompanies an architecture diagram with pointers to detailed...

  • README files
    README
    A readme file contains information about other files in a directory or archive and is commonly distributed with computer software. Such a file is usually a text file called README.TXT, README.1ST, READ.ME, or simply README, although some Microsoft Windows software may occasionally include a...

  • Unified Modeling Language
    Unified Modeling Language
    Unified Modeling Language is a standardized general-purpose modeling language in the field of object-oriented software engineering. The standard is managed, and was created, by the Object Management Group...

     UML
  • Literate programming
    Literate programming
    Literate programming is an approach to programming introduced by Donald Knuth as an alternative to the structured programming paradigm of the 1970s....


External links

  • kelp - a source code annotation framework for architectural, design and technical documentation.
  • ISO documentation standards committee - International Organization for Standardization committee which develops user documentation standards.
The source of this article is wikipedia, the free encyclopedia.  The text of this article is licensed under the GFDL.
 
x
OK