Content deleted Content added
I am VN123 (talk | contribs) No edit summary |
Minilexikon (talk | contribs) m Group related sections under a parent section for better structure |
||
Line 11:
* 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 shall 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]]s, [[customer]]s, [[project manager]]s, [[sales]], [[marketing]], [[software architect]]s, [[usability engineering|usability engineers]], [[interaction design]]ers, [[software developer|developer]]s, and [[Software testing|testers]].
Line 24 ⟶ 25:
In Agile software development, requirements are often expressed as User Stories with accompanying acceptance criteria.
=== 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 52 ⟶ 53:
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}}
Line 59 ⟶ 60:
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 67 ⟶ 68:
A possible 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.
===== 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 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.
=== User documentation ===
Unlike code documents, user documents simply describe how a program is used.
Line 101 ⟶ 102:
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 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.
==== 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>
Line 109 ⟶ 110:
# [[Usability testing]], whereby the usability of the document is tested empirically.<ref>Barker, pg. 240.</ref>
# [[Editing]], 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 for becoming more involved with it.▼
# 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 ⟶ 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>
▲== 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 for becoming more involved with it.
▲# 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.
== See also ==
| |||