|
== Types ==
=== Requirements documentation ===
[[Requirement]]sRequirements documentation is the description of what a particular software does or should do. It is used throughout [[Software development|development]] to communicate how the software functions or how it is intended to operate. It is also used as an agreement or as the foundation for agreement on what the software will do. Requirements are produced and consumed by everyone involved in the production of software, including: [[end user]]susers, [[customer]]scustomers, [[project manager]]smanagers, [[sales]], [[marketing]], [[software architect]]sarchitects, [[usability engineering|usability engineers]], [[interaction design]]ersdesigners, [[software developer|developer]]sdevelopers, and [[Software testing|testers]].
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 selecting the 'build' function''), and anything in between. They can be specified as statements in [[natural language]], as drawn figures, as detailed [[mathematical formula]]sformulas, or as a combination of them all.
The variation and complexity of requirement documentation make 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 [[Service life|life expectancy]] of the software. If the software is very complex or developed by many people (e.g., mobile phone software), requirements can help better communicate what to achieve. If the software is safety-critical and can have a negative impact on human life (e.g., nuclear power systems, medical equipment, mechanical 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]] tools are advocated.
In Agile software development, requirements are often expressed as [[User story|''user stories'']] with accompanying acceptance criteria. User stories are typically part of a feature, or an epic, which is a broader functionality or set of related functionalities that deliver a specific value to the user based on the business requirements.
=== Architecture design documentation ===
Architecture documentation (also known as [[software architecture description]]) is a special type 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 on explanation. It may suggest approaches for lower level design, but leave the actual exploration trade studies to other documents.
Another type of design document 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 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 administrator]]
*Application designer
*[[Programmer|Application developer]]
When talking about [[Relational Database]] Systems, the document should include following parts:
*[[Entity–relationship model|Entity - Relationship Schema]] ([[Enhanced Entity-Relationship Model|enhanced]] or not), including following information and their clear definitions:
**Entity Sets and their attributes
**Relationships and their attributes
=== 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 writer]]swriters. This documentation may be used by developers, testers, and also end-users. Today, a lot of high-end applications are seen in the fields 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. There is evidence that the existence of good code documentation actually reduces maintenance costs for software.<ref>{{cite web| url = https://hci.com.au/get-documentation-budget/ | title = How to get a budget for code documentation.}}</ref> ▼
{{Main article|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 writer]]s. This documentation may be used by developers, testers, and also end-users. Today, a lot of high-end applications are seen in the fields 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. There is evidence that the existence of good code documentation actually reduces maintenance costs for software.<ref>{{cite web| url = https://hci.com.au/get-documentation-budget/ | title = How to get a budget for code documentation.}}</ref>
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, [[Documentation generator|tools]] such as [[Doxygen]], [[NDoc]], [[Visual Expert]], [[Javadoc]], [[JSDoc]], [[EiffelStudio]], [[Sandcastle (software)|Sandcastle]], [[ROBODoc]], [[Plain Old Documentation|POD]], [[TwinText]], or Universal Report can be used to auto-generate the code documents—that is, they extract the comments and [[Design by Contract|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 [[comment (computer programming)|comment]]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.
===== 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 (programming language)|Haskell]] and [[CoffeeScript]] have built-in support for a simple form of literate programming, but this support is not widely used.
===== Elucidative programming =====
| 