Content deleted Content added
https://vm.tiktok.com/ZSNsVtQQb/ Tags: Reverted Visual edit Mobile edit Mobile web edit |
Undid revision 1304974754 by 2605:A601:A554:A601:6C23:A7A1:A614:5B83 (talk) |
||
| (37 intermediate revisions by 30 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 ===
Line 75 ⟶ 76:
=== 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 ====
Line 105 ⟶ 107:
# [[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.
Line 123 ⟶ 125:
A survey among software engineering experts revealed, however, that documentation is by no means considered unnecessary in agile development.
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 ===
'''Docs as Code''' is an approach to documentation that treats it with the same rigor and processes as software code. This includes:
# '''Version Control''': Using systems like Git to track changes and manage versions.
# '''Continuous Integration''': Automating the process of documentation generation and updates.
# '''Collaboration''': Enabling multiple contributors to work on documentation simultaneously, similar to code development.
==== 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 ==
| |||