Content deleted Content added
No edit summary Tags: Reverted Visual edit Mobile edit Mobile web edit |
Undid revision 1304974754 by 2605:A601:A554:A601:6C23:A7A1:A614:5B83 (talk) |
||
| (16 intermediate revisions by 15 users not shown) | |||
Line 1:
{{Short description|Explains the functionality of software}}
{{Software development process}}
'''Software documentation''' is written text or illustration that accompanies computer software or is embedded in the source code. The documentation either explains how the software operates or how to use it, and may mean different things to people in different roles.
[[Documentation]] is an important part of software engineering. Types of documentation include:
*
* Architecture/Design – Overview of software. Includes relations to an environment and construction principles to be used in design of software components.
* Technical – Documentation of code, algorithms, interfaces, and APIs.
Line 13 ⟶ 12:
== Types ==
=== Requirements documentation ===
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
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 ===
Line 84 ⟶ 83:
Typically, the user documentation describes each feature of the program, and assists the user in realizing these features. It is very important for user documents to not be confusing, and for them to be up to date. User documents do not need to be organized in any particular way, but it is very important for them to have a thorough [[Index (publishing)|index]]. Consistency and simplicity are also very valuable. User documentation is considered to constitute a contract specifying what the software will do. [[API Writer]]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]].
User documentation can be produced in a variety of online and print formats.<ref>{{cite
# '''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.<ref name=kdp>{{cite web
| last = Woelz
| first = Carlos
| title = The KDE Documentation Primer
| url =
| access-date = 15 June 2009 }}</ref>
# '''Thematic:''' A [[Theme (literature)|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]].<ref name=kbad>{{cite web
| |||