Content deleted Content added
No edit summary |
Undid revision 1304974754 by 2605:A601:A554:A601:6C23:A7A1:A614:5B83 (talk) |
||
| (46 intermediate revisions by 38 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
[[Documentation]] is an important part of software engineering. Types of documentation include:
* [[Requirement]]s – Statements that identify attributes, capabilities, characteristics, or qualities of a system. This is the foundation for what will be or has been implemented.
* 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
*
* Marketing – How to market the product and analysis of the market demand.
== Types ==
=== Requirements documentation === [[Requirement]]s documentation is the description of what a particular software does or
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]]s, or as a combination of them all.
Line 21 ⟶ 22:
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
=== 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.
Line 51 ⟶ 52:
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 ===
{{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.
Line 64 ⟶ 65:
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 =====
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.
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 [[annotation]]s are usually part of several software development activities, such as code walks and porting, where third
=== User documentation ===
{{About|section=yes|consumable guides for software usage|more general systems|End user documentation}}
Unlike code documents, user documents simply describe how a program is used.
In the case of a [[Library (computing)|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. It is very important for user documents to not be confusing, and for them to be up to date. User documents
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
Line 98 ⟶ 100:
# '''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]]s to [[online help]] that
==== 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:<ref>Thomas T. Barker, [http://www.writingsoftwaredocumentation.com/index.htm Writing Software Documentation], Preface, xxiv. Part of the [[Allyn & Bacon]] Series in Technical Communication, 2nd ed. [[Upper Saddle River, New Jersey|Upper Saddle River]]: [[Pearson Education]], 2003. {{ISBN|0321103289}} {{webarchive |url=https://web.archive.org/web/20130513033153/http://www.writingsoftwaredocumentation.com/index.htm |date=May 13, 2013 }}</ref>
# [[User analysis]], the basic research phase of the process.<ref>Barker, pg. 118.</ref>
# Planning, or the actual documentation phase.<ref>Barker, pg. 173.</ref>
# Draft review, is a self-explanatory phase where feedback is sought on the draft composed in the previous step.<ref>Barker, pg. 217.</ref>
# [[Usability testing]], whereby the usability of the document is tested empirically.<ref>Barker, pg. 240.</ref>
# [[Editing]], is the final step in which the information collected in steps three and four is used to produce the final draft.
=== 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:▼
# To excite the potential user about the product and instill in them a desire
# To inform them about what exactly the product does, so that their expectations are in line with what they will be receiving.▼
# To explain the position of this product with respect to other alternatives.▼
== Documentation and agile development controversy ==
Line 117 ⟶ 126:
Yet it is acknowledged that there are motivational problems in development, and that documentation methods tailored to agile development (e.g. through [[Reputation system]]s and [[Gamification]]) may be needed.<ref>Prause, Christian R., and Zoya Durdik. "Architectural design and documentation: Waste in agile development?" In: ''International Conference on Software and System Process'' (ICSSP), IEEE, 2012.</ref><ref>Selic, Bran. "Agile documentation, anyone?" In: ''IEEE Software'', vol. 26, no. 6, pp. 11-12, 2009</ref>
=== Docs as Code ===
▲== Marketing documentation ==
'''Docs as Code''' is an approach to documentation that treats it with the same rigor and processes as software code. This includes:
▲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:
# '''Version Control''': Using systems like Git to track changes and manage versions.
▲# To excite the potential user about the product and instill in them a desire for becoming more involved with it.
# '''Continuous Integration''': Automating the process of documentation generation and updates.
▲# To inform them about what exactly the product does, so that their expectations are in line with what they will be receiving.
# '''Collaboration''': Enabling multiple contributors to work on documentation simultaneously, similar to code development.
▲# To explain the position of this product with respect to other alternatives.
==== Benefits of Docs as Code ====
* '''Consistency''': Documentation can be kept in sync with the codebase, ensuring accuracy.
* '''Automation''': Automated tools can handle repetitive tasks, such as formatting and deployment.
* '''Collaboration''': Encourages contributions from various team members, including developers, testers, and product managers.Combining Docs as Code with Agile methodologies creates a robust framework for maintaining high-quality, up-to-date documentation. Here's how to integrate the two:
# '''Setup Version Control''': Start by placing your documentation in a version control system. Structure it similarly to your codebase.
# '''Automate Processes''': Implement CI/CD tools to automate the generation and deployment of documentation.
# '''Define Roles''': Assign roles and responsibilities for documentation within the Agile team. Ensure everyone understands the importance of documentation.
# '''Regular Reviews''': Schedule regular documentation reviews as part of the sprint retrospectives.
== See also ==
| |||