Software documentation

From Wikipedia, the free encyclopedia

Jump to: navigation, search
This article needs additional citations for verification.
Please help improve this article by adding reliable references. Unsourced material may be challenged and
removed. (August 2010)
Software documentation or source code documentation is written text that accompanies
computer software. It either explains how it operates or how to use it, and may mean different
things to people in different roles.

Contents
• 1 Involvement of people in software life
○ 1.1 Requirements documentation
○ 1.2 Architecture/Design documentation
○ 1.3 Technical documentation
○ 1.4 User documentation
○ 1.5 Marketing documentation
• 2 Notes
• 3 See also
• 4 External links

[edit] Involvement of people in software life

Documentation is an important part of software engineering. Types of documentation include:
1. Requirements - Statements that identify attributes, capabilities, characteristics, or
qualities of a system. This is the foundation for what shall be or has been implemented.
2. Architecture/Design - Overview of softwares. Includes relations to an environment and
construction principles to be used in design of software components.
3. Technical - Documentation of code, algorithms, interfaces, and APIs.
4. End User - Manuals for the end-user, system administrators and support staff.
5. Marketing - How to market the product and analysis of the market demand.
[edit] Requirements documentation
Requirements documentation is the description of what a particular software does or shall do. It
is used throughout development to communicate what the software does or shall do. It is also
used as an agreement or as the foundation for agreement on what the software shall do.
Requirements are produced and consumed by everyone involved in the production of software:
end users, customers, product managers, project managers, sales, marketing, software architects,
usability engineers, interaction designers, developers, and testers, to name a few. Thus,
requirements documentation has many different purposes.
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 select the 'build' function), and anything in between. They can be
specified as statements in natural language, as drawn figures, as detailed mathematical formulas,
and as a combination of them all.
The variation and complexity of requirements documentation makes 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 that 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 life expectancy of the software. If the software is very
complex or developed by many people (e.g., mobile phone software), requirements can help to
better communicate what to achieve. If the software is safety-critical and can have negative
impact on human life (e.g., nuclear power systems, medical 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.
[edit] Architecture/Design documentation
Architecture documentation is a special breed 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 breed of design docs 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 Designer
• Database Developer
• Database Administrator
• Application Designer
• Application Developer
When talking about Relational Database Systems, the document should include following parts:
• Entity - Relationship Schema, including following information and their clear definitions:
○ Entity Sets and their attributes
○ Relationships and their attributes
○ Candidate keys for each entity set
○ Attribute and Tuple based constraints
• Relational Schema, including following information:
○ Tables, Attributes, and their properties
○ Views
○ Constraints such as primary keys, foreign keys,
○ Cardinality of referential constraints
○ Cascading Policy for referential constraints
○ Primary keys
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.
[edit] Technical documentation
This is what most programmers mean when using the term software documentation. When
creating software, code alone is insufficient. There must be some text along with it to describe
various aspects of its intended operation. It is important for the code documents to be thorough,
but not so verbose that it becomes difficult to maintain them. Several How-to and overview
documentation are found specific to the software application or software product being
documented by API Writers. This documentation may be used by developers, testers and also the
end customers or clients using this software application. Today, we see lot of high end
applications in the field 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. Hence, technical documentation has gained lot
of importance in recent times, especially in the software field.
Often, tools such as Doxygen, NDoc, javadoc, EiffelStudio, Sandcastle, ROBODoc, POD,
TwinText, or Universal Report can be used to auto-generate the code documents—that is, they
extract the comments and software contracts, where available, from the source code and create
reference manuals in such forms as text or HTML files. Code documents are often organized into
a reference guide style, allowing a programmer to quickly look up an arbitrary function or class.
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 comments),
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.
Of course, a 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.
Donald Knuth has insisted on the fact that documentation can be a very difficult afterthought
process and has advocated literate programming, writing at the same time and location as the
source code and extracted by automatic means.
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. This paradigm was inspired by the same experimental findings that
produced Kelp. 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 annotations 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. Kelp stores
annotations in separate files, linking the information to the source code dynamically.
[edit] User documentation
Unlike code documents, user documents are usually far more diverse with respect to the source
code of the program, and instead simply describe how it is used.
In the case of a software library, the code documents and user documents could be effectively
equivalent and are 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. A good user document can also go so far as to provide thorough
troubleshooting assistance. It is very important for user documents to not be confusing, and for
them to be up to date. User documents need not be organized in any particular way, but it is very
important for them to have a thorough index. Consistency and simplicity are also very valuable.
User documentation is considered to constitute a contract specifying what the software will do.
API Writers 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.
There are three broad ways in which user documentation can be organized.
1. 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 [1].
 2. Thematic: A 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 facilitating the user needs. This
approach is usually practiced by a dynamic industry, such as Information technology,
where the user population is largely correlated with the troubleshooting demands [2], [3].
3. 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 computers 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.
[edit] 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:-
1. To excite the potential user about the product and instill in them a desire for becoming
more involved with it.
2. To inform them about what exactly the product does, so that their expectations are in line
with what they will be receiving.
3. To explain the position of this product with respect to other alternatives.
One good marketing technique is to provide clear and memorable catch phrases that exemplify
the point we wish to convey, and also emphasize the interoperability of the program with
anything else provided by the manufacturer.
[edit] Notes
1. ^ Woelz, Carlos. "The KDE Documentation Primer". http://i18n.kde.org/docs/doc-
primer/index.html. Retrieved 15 June 2009.
2. ^ Microsoft. "Knowledge Base Articles for Driver Development".
http://www.microsoft.com/whdc/driver/kernel/kb-drv.mspx. Retrieved 15 June 2009. [dead
link]

3. ^ Prekaski, Todd. "Building web and Adobe AIR applications from a shared Flex code
base". http://www.adobe.com/devnet/air/flex/articles/flex_air_codebase.html. Retrieved
15 June 2009.
[edit] See also
• API Writer
• Comparison of documentation generators
• Design by contract
• Docstring
 • Documentation
• User Assistance
• Design document
• README files
• Unified Modeling Language UML
• Literate programming
[edit] External links
• kelp - a source code annotation framework for architectural, design and technical
documentation.
• ISO documentation standards committee - International Organization for Standardization
committee which develops user documentation standards.
v · d · eSoftware engineering

Requirements analysis • Systems analysis • Software design • Computer

Fields programming • Formal methods • Software testing • Software deployment •
Software maintenance

Data modeling • Enterprise architecture • Functional specification • Modeling

language • Programming paradigm • Software • Software architecture • Software
Concepts
development methodology • Software development process • Software quality •
Software quality assurance • Software archaeology • Structured analysis

Orientation Agile • Aspect-oriented • Object orientation • Ontology • Service orientation •

s SDLC

DevelopmentAgile • Iterative model • RUP • Scrum • Spiral model • Waterfall

models model • XP • V-Model • Incremental model • Prototype model

Automotive SPICE • CMMI • Data model • Function model •

Other
Models Information model • Metamodeling • Object model • Systems model •
models
View model

Modeling
IDEF • UML
languages

Kent Beck • Grady Booch • Fred Brooks • Barry Boehm • Ward Cunningham • Ole-
Johan Dahl • Tom DeMarco • Martin Fowler • C. A. R. Hoare • Watts Humphrey •
Software
Michael A. Jackson • Ivar Jacobson • Craig Larman • James Martin • Bertrand
engineers
Meyer • David Parnas • Winston W. Royce • Colette Rolland • James Rumbaugh •
Niklaus Wirth • Edward Yourdon • Victor Basili

Related Computer science • Computer engineering • Enterprise engineering • History •

fields Management • Project management • Quality management • Software ergonomics •
 Systems engineering
Retrieved from "http://en.wikipedia.org/wiki/Software_documentation"
Categories: Software documentation | Technical communication
Hidden categories: All articles with dead external links | Articles with dead external links from
September 2010 | Articles needing additional references from August 2010 | All articles needing
additional references
Personal tools
• Log in / create account
Namespaces
• Article
• Discussion
Variants
Views
• Read
• Edit
• View history
Actions
Search
Top of Form
Special:Search

Bottom of Form

Navigation
• Main page
• Contents
• Featured content
• Current events
• Random article
• Donate to Wikipedia
Interaction
• Help
• About Wikipedia
• Community portal
• Recent changes
• Contact Wikipedia
Toolbox
• What links here
• Related changes
• Upload file
• Special pages
• Permanent link
• Cite this page
Print/export
• Create a book
• Download as PDF
• Printable version
Languages
• Deutsch
• Français
• 日本語
• Polski
• Português
• Русский
• This page was last modified on 8 February 2011 at 18:15.
• Text is available under the Creative Commons Attribution-ShareAlike License;
additional terms may apply. See Terms of Use for details.
Wikipedia® is a registered trademark of the Wikimedia Foundation, Inc., a non-profit
organization.
• Contact us
• Privacy policy
• About Wikipedia
• Disclaimers
•
•