FACTOID # 2: Puerto Rico has roughly the same gross state product as Montana, Wyoming and North Dakota combined.
 
 Home   Encyclopedia   Statistics   States A-Z   Flags   Maps   FAQ   About 
   
 
WHAT'S NEW
 

SEARCH ALL

FACTS & STATISTICS    Advanced view

Search encyclopedia, statistics and forums:

 

 

(* = Graphable)

 

 


Encyclopedia > Software documentation

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. This article is about the machine. ... Computer software (or simply software) refers to one or more computer programs and data held in the storage of a computer for some purpose. ...

Contents

Types of Documentation

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.
  • End User - Manuals for the end-user, system administrators and support staff.
  • Marketing - Product briefs and promotional collateral.

Architecture/Design Documentation

Architecture documentation is a special breed of design documents. In a way, architecture documents are third derivative from the code (design documents 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 IS 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 white paper is a government report outlining policy or authoritative report on a major issue. ... The user interface is the part of a system exposed to users. ... For the glossary of hacker slang, see Jargon File. ...


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. A programmer or software developer is someone who programs computers, that is, one who writes computer software. ... Computer software (or simply software) refers to one or more computer programs and data held in the storage of a computer for some purpose. ... Source code (commonly just source or code) is any series of statements written in some human-readable computer programming language. ...


Often, tools such as Doxygen, javadoc, ROBODoc, POD or TwinText can be used to auto-generate the code documents—that is, they extract the comments 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. Doxygen is a documentation generator for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors) and to some extent PHP, C#, D and ActionScript. ... Javadoc is a computer software tool from Sun Microsystems for generating API documentation into HTML format from Java source code. ... ROBODoc is a documentation tool similar to javadoc. ... Plain Old Documentation, commonly abbreviated as POD, is a simple platform-independent documentation tool for the computer language Perl. ... TwinText is a commercially available Source Code Documentation Tool. ... HTML, short for Hypertext Markup Language, is the predominant markup language for web pages. ...


Many programmers really like the idea of auto-generating documentation 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 his code, and can use the same tools he used to create the source code, to make the documentation. This makes it much easier to keep the documentation up-to-date. An illustration of Java source code with prologue comments indicated in red and inline comments in green. ...


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. The crontab command, found in Unix and Unix-like operating systems, is used to schedule commands to be executed periodically. ...


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. Donald Ervin Knuth ( or Ka-NOOTH[1], Chinese: [2]) (b. ... Literate programming is the writing of computer programs primarily for human beings to read, similar to a work of literature; hence the name literate programming. ... Source code (commonly just source or code) is any series of statements written in some human-readable computer programming language. ...


Elucidative Programming is the result of an 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. Annotation is extra information associated with a particular point in a document or other piece of information. ...


User Documentation

Unlike code documents, user documents are usually far divorced from 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. On the other hand, the Lisp machine grew out of a tradition in which every piece of code had an attached documentation string. In combination with strong search capabilities (based on a Unix-like apropos command), and online sources, Lispm users could look up documentation and paste the associated function directly into their own code. This level of ease of use is unheard of in putatively more modern systems. In computer science, a library is a collection of subprograms used to develop software. ... The original Lisp machine built by Greenblatt and Knight Lisp machines were general-purpose computers designed (usually through hardware support) to efficiently run Lisp as their main software language. ... Filiation of Unix and Unix-like systems Unix (officially trademarked as UNIX®) is a computer operating system originally developed in 1969 by a group of AT&T employees at Bell Labs including Ken Thompson, Dennis Ritchie and Douglas McIlroy. ...


Typically, the user documentation describes each feature of the program, and assists the user in realising 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. See also Technical Writing. Troubleshooting is a form of problem solving. ... An index is a detailed list, usually arranged alphabetically, of the specific information in a publication, whether a book, periodical, database or multimedia collection. ... Technical writing, a subset of technical communication, is used in fields as diverse as computer hardware and software, chemistry, the aerospace industry, robotics, finance, consumer electronics, and biotechnology. ...


There are three broad ways in which user documentation can be organized.

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.
Thematic
A thematic approach, where chapters or sections concentrate on one particular area of interest, is of more general use to an intermediate user.
List
The final type of organizing principle is one in which commands or tasks are simply listed alphabetically, often via cross-referenced indices. This latter approach is of the greatest 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. // Academia In British academic parlance, a tutorial is a small class of one, or only a few, students, in which the tutor (a professor or other academic staff member) gives individual attention to the students. ... In literature, a theme is a broad idea in a story, or a message or lesson conveyed by a work. ... Online Help is topic, procedural or reference information delivered through computer software. ...


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.


Tools for architectural, design and technical documentation

  • kelp - a source code annotation system

Software engineering and documentation methodologies

In the field of software engineering, the Unified Modeling Language (UML) is a standardized specification language for object modeling. ... Literate programming is the writing of computer programs primarily for human beings to read, similar to a work of literature; hence the name literate programming. ...

See also


  Results from FactBites:
 
Software documentation - Wikipedia, the free encyclopedia (1420 words)
Software Documentation or Source Code Documentation is written text that accompanies computer software.
Documentation is an important part of software engineering that is often overlooked.
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.
FSF - Licenses (6671 words)
This is a free software license, and a copyleft license.
This is a free software license, not a strong copyleft, and incompatible with the GNU GPL.
This is not a free software license, because it
  More results at FactBites »

 
 

COMMENTARY     


Share your thoughts, questions and commentary here
Your name
Your comments

Want to know more?
Search encyclopedia, statistics and forums:

 


Press Releases |  Feeds | Contact
The Wikipedia article included on this page is licensed under the GFDL.
Images may be subject to relevant owners' copyright.
All other elements are (c) copyright NationMaster.com 2003-5. All Rights Reserved.
Usage implies agreement with terms, 1022, m