Friday, February 20, 2009

Software engineer

From Wikipedia, the free encyclopedia

Jump to: navigation, search

A software engineer is a person who applies the principles of software engineering to the design, development, testing, and evaluation of the software and systems that make computers or anything with software such as chips work. Positives of this career are the good money, option of working at home, and it's perfect for people that want to work with computers and have a predilection for them.[1]

Overview

Prior to the mid-1990s, most software practitioners called themselves programmers or developers, regardless of their actual jobs. Many people prefer to call themselves software developer and programmer, because most widely agree what these terms mean, while software engineer is still being debated.

The term programmer has often been used as a pejorative term to refer to those who lacked the tools, skills, education, or ethics to write good quality software. In response, many practitioners called themselves software engineers to escape the stigma attached to the word programmer. In many companies, the titles programmer and software developer were changed to software engineer, for many categories of programmers.

These terms cause confusion, because some denied any differences (arguing that everyone does essentially the same thing with software) while others use the terms to create a difference (because the terms mean completely different jobs).

A state of the art

In 2004, the U. S. Bureau of Labor Statistics counted 760,840 software engineers holding jobs in the U.S.; in the same time period there were some 1.4 million practitioners employed in the U.S. in all other engineering disciplines combined.[2] Due to its relative newness as a field of study, formal education in software engineering is often taught as part of a computer science curriculum, and as a result most software engineers hold computer science degrees.[3] The term software engineer is used very liberally in the corporate world. Very few of the practicing software engineers actually hold Engineering degrees from accredited universities. In fact, according to the Association for Computing Machinery, "most people who now function in the U.S. as serious software engineers have degrees in computer science, not in software engineering". See also Debates within software engineering and Controversies over the term Engineer.

Regulatory classification

The U.S. Bureau of Labor Statistics classifies computer software engineers as a subcategory of "computer specialists", along with occupations such as computer scientist, programmer, and network administrator.[4] The BLS classifies all other engineering disciplines, including computer hardware engineers, as "engineers".[5]

The U.K. has seen the alignment of the Information Technology Professional and the Engineering Professionals.[6]

Software engineering in Canada has seen some contests in the courts over the use of the title "Software Engineer"[7] The Canadian Council of Professional Engineers (C.C.P.E. or "Engineers Canada") will not grant a "Professional Engineer" status/license to anyone who has not completed a recognized academic engineering program.[citation needed] Engineers qualified outside Canada are similarly unable to obtain a "Professional Engineer" license.[8] Since 2001, the Canadian Engineering Accreditation Board has accredited several university programs in software engineering[9], allowing graduates to apply for a professional engineering licence once the other prerequisites are obtained, although this does nothing to help IT professionals using the title with degrees in other fields (such as computer science).

Some of the United States of America regulate the use of terms such as "computer engineer" and even "software engineer". These states include at least Texas[10] and Florida[11]. Texas even goes so far as to ban anyone from writing any real-time code without an engineering license.

Education


 The examples and perspective in this article deal primarily with North America and do not represent a worldwide view of the subject. Please improve this article or discuss the issue on the talk page.

About half of all practitioners today have computer science degrees. A small, but growing, number of practitioners have software engineering degrees. In 1987 Imperial College London introduced the first three year software engineering Bachelor's degree in the UK and the world, in the following year the University of Sheffield established a similar programme[12]. In 1996, Rochester Institute of Technology established the first software engineering Bachelor's degree program in the United States, however, it did not obtain ABET until 2003, the same time as Clarkson University, Milwaukee School of Engineering and Mississippi State University.[13]

Since then, software engineering undergraduate degrees have been established at many universities. A standard international curriculum for undergraduate software engineering degrees was recently defined by the CCSE. As of 2004, in the U.S., about 50 universities offer software engineering degrees, which teach both computer science and engineering principles and practices. The first software engineering Master's degree was established at Seattle University in 1979. Since then graduate software engineering degrees have been made available from many more universities. Likewise in Canada, the Canadian Engineering Accreditation Board (CEAB) of the Canadian Council of Professional Engineers has recognized several software engineering programs.

In 1998, the US Naval Postgraduate School (NPS) established the first doctorate program in Software Engineering in the world.[citation needed] Additionally, many online advanced degrees in Software Engineering have appeared such as the Master of Science in Software Engineering (MSE) degree offered through the Computer Science and Engineering Department at California State University, Fullerton. Steve McConnell opines that because most universities teach computer science rather than software engineering, there is a shortage of true software engineers.[14] ETS University and UQAM were mandated by IEEE to develop the SoftWare Engineering BOdy of Knowledge SWEBOK, which has become an ISO standard describing the body of knowledge covered by a software engineer[citation needed].

Other degrees

In business, some software engineering practitioners have MIS degrees. In embedded systems, some have electrical or computer engineering degrees, because embedded software often requires a detailed understanding of hardware. In medical software, practitioners may have medical informatics, general medical, or biology degrees.[citation needed]

Some practitioners have mathematics, science, engineering, or technology degrees. Some have philosophy (logic in particular) or other non-technical degrees.[citation needed] And, others have no degrees.[citation needed] For instance, Barry Boehm earned degrees in mathematics.

Profession

Employment

See also: software engineering demographics

Most software engineers work as employees or contractors. Software engineers work with businesses, government agencies (civilian or military), and non-profit organizations. Some software engineers work for themselves as freelancers. Some organizations have specialists to perform each of the tasks in the software development process. Other organizations required software engineers to do many or all of them. In large projects, people may specialize in only one role. In small projects, people may fill several or all roles at the same time. Specializations include: in industry (analysts, architects, developers, testers, technical support, managers) and in academia (educators, researchers).

There is considerable debate over the future employment prospects for Software Engineers and other IT Professionals. For example, an online futures market called the Future of IT Jobs in America attempts to answer whether there will be more IT jobs, including software engineers, in 2012 than there were in 2002.

Certification

Professional certification of software engineers is a contentious issue.[citation needed] Some see it as a tool to improve professional practice.[citation needed]

Most successful certification programs in the software industry are oriented toward specific technologies, and are managed by the vendors of these technologies.[citation needed] These certification programs are tailored to the institutions that would employ people who use these technologies.

The ACM had a professional certification program in the early 1980s, which was discontinued due to lack of interest. [15]. As of 2006, the IEEE had certified over 575 software professionals.[16] In Canada the Canadian Information Processing Society has developed a legally recognized professional certification called Information Systems Professional (ISP).[17]

Impact of globalization

Many students in the developed world have avoided degrees related to software engineering because of the fear of offshore outsourcing (importing software products or services from other countries) and of being displaced by foreign visa workers.[18] Although government statistics do not currently show a threat to software engineering itself; a related career, computer programming does appear to have been affected.[19][20] Often one is expected to start out as a computer programmer before being promoted to software engineer. Thus, the career path to software engineering may be rough, especially during recessions.

Some career counselors suggest a student also focus on "people skills" and business skills rather than purely technical skills because such "soft skills" are allegedly more difficult to offshore.[21] It is the quasi-management aspects of software engineering that appear to be what has kept it from being impacted by globalization.[22]

Prizes

There are several prizes in the field of software engineering[23]:

  • The CODiE awards is a yearly award issued by the Software and Information Industry Association for excellence in software development the software industry.
  • Jolt Awards are awards in the software industry.
  • Stevens Award is a software engineering award given in memory of Wayne Stevens.

Debates within software engineering

Main article: Debates within software engineering

Controversies over the term Engineer

Main article: Controversies over the term Engineer

Some people believe that software engineering implies a certain level of academic training, professional discipline, and adherence to formal processes that often are not applied in cases of software development. A common analogy is that working in construction does not make one a civil engineer, and so writing code does not make one a software engineer. It is disputed by some - in particular by the Canadian Professional Engineers Ontario (PEO) body, that the field is mature enough to warrant the title "engineering". The PEO's position was that "software engineering" was not an appropriate name for the field since those who practiced in the field and called themselves "software engineers" were not properly licensed professional engineers, and that they should therefore not be allowed to use the name.[24]

The status of software engineering

The word engineering within the term software engineering causes a lot of confusion.

The wrangling over the status of software engineering (between traditional engineers and computer scientists) can be interpreted as a fight over control of the word engineering. Traditional engineers question whether software engineers can legally use the term[citation needed].

Traditional engineers (especially civil engineers and the NSPE) claim that they have special rights over the term engineering, and for anyone else to use it requires their approval. In the mid-1990s, the NSPE sued to prevent anyone from using the job title software engineering. The NSPE won their lawsuit in 48 states[citation needed]. However, SE practitioners, educators, and researchers ignored the lawsuits and called themselves software engineers anyway. The U.S. Bureau of Labor Statistics uses the term software engineer, too. The term engineering is much older than any regulatory body, so many believe that traditional engineers have few rights to control the term. As things stand at 2007, however, even the NSPE appears to have softened its stance towards software engineering and following the heels of several overseas precedents, is investigating a possibility of licensing software engineers in consultation with IEEE, NCEES and other groups "for the protection of the public health safety and welfare" [25].

In Canada, the use of the words 'engineer' and 'engineering' are controlled in each province by self-regulating professional engineering organizations, often aligned with geologists and geophysicists, and tasked with enforcement of the governing legislation. The intent is that any individual holding themselves out as an engineer (or geologist or geophysicist) has been verified to have been educated to a certain accredited level, and their professional practice is subject to a code of ethics and peer scrutiny. This system was originally designed for the practise of engineering where public safety is a concern, but extends to other branches of engineering as well, including electronics and software[citation needed].

In New Zealand, IPENZ, the professional engineering organization entrusted by the New Zealand government with legal power to license and regulate chartered engineers (CPEng), recognizes software engineering as a legitimate branch of professional engineering and accepts application of software engineers to obtain chartered status provided he or she has a tertiary degree of approved subjects. Software Engineering is included but Computer Science is normally not. [26]

[edit] See also


 Wikimedia Commons has media related to: Software engineers

References

  1. ^ Occupational Outlook Handbook, 2006–07 Edition.
  2. ^ Bureau of Labor Statistics, U.S. Department of Labor, USDL 05-2145: Occupational Employment and Wages, November 2004, Table 1.
  3. ^ "Software Engineering". http://computingcareers.acm.org/?page_id=12. Retrieved on 2008-02-01.
  4. ^ U.S Department of Labor and Statistics The 2000 Standard Occupational Classification (SOC) System: 15-0000 Computer and Mathematical Occupations
  5. ^ U.S Department of Labor and Statistics The 2000 Standard Occupational Classification (SOC) System: 17-0000 Architecture and Engineering Occupations
  6. ^ 'British Computer Society' - "BCS is licensed by the Engineering Council to award Chartered Engineer status (CEng) and Incorporated Engineer status (IEng);" [1]
  7. ^ 'Professional Engineers of Ontario' - "Quebec Engineers win court battle against Microsoft"[2]
  8. ^ Council for Access to the Profession of Engineering
  9. ^ Accredited Engineering Programs in Canada
  10. ^ IEEE Software: "What do you mean I can't call myself a Software Engineer?"
  11. ^ Florida Statutes: Chapter 471: Engineering
  12. ^ Cowling, A. J. 1999. The first decade of an undergraduate degree programme in software engineering. Ann. Softw. Eng. 6, 1-4 (Apr. 1999), 61-90.
  13. ^ "ABET Accredited Engineering Programs". April 3, 2007. http://www.abet.org/accrediteac.asp. Retrieved on 2007-04-03.
  14. ^ McConnell, Steve (July 10, 2003. Professional Software Development: Shorter Schedules, Higher Quality Products, More Successful Projects, Enhanced Careers. ISBN 978-0321193674.
  15. ^ Actually the ACM made an explicit decision not to continue with certification. 1
  16. ^ IEEE Computer Society. "2006 IEEE COMPUTER SOCIETY REPORT TO THE IFIP GENERAL ASSEMBLY". http://www.ifip.org/minutes/GA2006/Tab18b-US-IEEE.pdf. Retrieved on 2007-04-10.
  17. ^ Canadian Information Processing Society. "I.S.P. Designation". http://www.cips.ca/standards/isp. Retrieved on 2007-03-15.
  18. ^ As outsourcing gathers steam, computer science interest wanes
  19. ^ Computer Programmers
  20. ^ Software developer growth slows in North America | InfoWorld | News | 2007-03-13 | By Robert Mullins, IDG News Service
  21. ^ Hot Skills, Cold Skills
  22. ^ Dual Roles: The Changing Face of IT
  23. ^ Some external links:
  24. ^ Sayo, Mylene, [http://www.peo.on.ca/enforcement/June112002newsrelease.html What's in a Name? Tech Sector battles Engineers on "software engineering"], http://www.peo.on.ca/enforcement/June112002newsrelease.html, retrieved on 2008-07-24
  25. ^ Report on 2007 NSPE Annual Conference
  26. ^ IPENZ, Good Practice Guidelines for Software Engineering in New Zealand http://www.ipenz.org.nz/ipenz/forms/pdfs/Software-engineering-guidelines.pdf
Retrieved from "http://en.wikipedia.org/wiki/Software_engineer"

Programmer

From Wikipedia, the free encyclopedia

(Redirected from Computer programmer)
Jump to: navigation, search
For other uses, see Programmer (disambiguation).

A programmer is someone who writes computer software. The term computer programmer can refer to a specialist in one area of computer programming or to a generalist who writes code for many kinds of software. One who practices or professes a formal approach to programming may also be known as a programmer analyst. A programmer's primary computer language (Lisp, Java, Delphi, C++, etc.) is often prefixed to the above titles, and those who work in a web environment often prefix their titles with web. A programmer is not a software developer, software engineer, computer scientist, or software analyst. These professions typically refer to individuals possessing programming skills as well as other software engineering skills. For this reason, the term programmer is sometimes considered an insulting or derogatory oversimplification of these other professions. This has sparked much debate amongst developers, analysts, computer scientists, programmers, and outsiders who continue to be puzzled at the subtle differences in these occupations.[1][2][3][4][5]

Those proficient in computer programming skills may become famous, though this regard is normally limited to software engineering circles. Many of the most notable programmers are often labeled hackers. Programmers often have or project an image of individualist geekdom, resistance to "suits" (referring to both business suits literally and figuratively to the "Establishment"), controls and conformity.

Ada Lovelace is popularly credited as history's first programmer. She was the first to express an algorithm intended for implementation on a computer, Charles Babbage's analytical engine, in October 1842.[6] Her work never ran, though that of Konrad Zuse did in 1941. The ENIAC programming team, consisting of Kay McNulty, Betty Jennings, Betty Snyder, Marlyn Wescoff, Fran Bilas and Ruth Lichterman were the first working programmers.[7][8]

International Programmers' Day is celebrated annually on January 7th.[9]

Nature of the work

Some of this section is from the Occupational Outlook Handbook, 2006–07 Edition, which is in the public domain as a work of the United States Government.

Computer programmers write, test, debug, and maintain the detailed instructions, called computer programs, that computers must follow to perform their functions. Programmers also conceive, design, and test logical structures for solving problems by computer. Many technical innovations in programming — advanced computing technologies and sophisticated new languages and programming tools — have redefined the role of a programmer and elevated much of the programming work done today. Job titles and descriptions may vary, depending on the organization.

Programmers work in many settings, including corporate information technology departments, big software companies, and small service firms. Many professional programmers also work for consulting companies at client' sites as contractors. Licensing is not typically required to work as a programmer, although professional certifications are commonly held by programmers. Programming is widely considered a profession (although some authorities disagree on the grounds that only careers with legal licensing requirements count as a profession).

Programmers' work varies widely depending on the type of business they are writing programs for. For example, the instructions involved in updating financial records are very different from those required to duplicate conditions on an aircraft for pilots training in a flight simulator. Although simple programs can be written in a few hours, programs that use complex mathematical formulas whose solutions can only be approximated or that draw data from many existing systems may require more than a year of work. In most cases, several programmers work together as a team under a senior programmer’s supervision.

Programmers write programs according to the specifications determined primarily by more senior programmers and by systems analysts. After the design process is complete, it is the job of the programmer to convert that design into a logical series of instructions that the computer can follow. The programmer codes these instructions in one of many programming languages. Different programming languages are used depending on the purpose of the program. COBOL, for example, is commonly used for business applications which are run on mainframe and midrange computers, whereas Fortran is used in science and engineering. C++ is widely used for both scientific and business applications. Java, C# and PHP are popular programming languages for Web and business applications. Programmers generally know more than one programming language and, because many languages are similar, they often can learn new languages relatively easily. In practice, programmers often are referred to by the language they know, e.g. as Java programmers, or by the type of function they perform or environment in which they work: for example, database programmers, mainframe programmers, or Web developers.

When making changes to the source code that programs are made up of, programmers need to make other programmers aware of the task that the routine is to perform. They do this by inserting comments in the source code so that others can understand the program more easily. To save work, programmers often use libraries of basic code that can be modified or customized for a specific application. This approach yields more reliable and consistent programs and increases programmers' productivity by eliminating some routine steps.

Testing and debugging

Programmers test a program by running it and looking for bugs. As they are identified, the programmer usually makes the appropriate corrections, then rechecks the program until an acceptably low level and severity of bugs remain. This process is called testing and debugging. These are important parts of every programmer's job. Programmers may continue to fix these problems throughout the life of a program. Updating, repairing, modifying, and expanding existing programs sometimes called maintenance programmer. Programmers may contribute to user guides and online help, or they may work with technical writers to do such work.

Certain scenarios or execution paths may be difficult to test, in which case the programmer may elect to test by inspection which involves a human inspecting the code on the relevant execution path, perhaps hand executing the code. Test by inspection is also sometimes used as a euphemism for inadequate testing. It may be difficult to properly assess whether the term is being used euphemistically.

Application versus system programming

Computer programmers often are grouped into two broad types: application programmers and systems programmers. Application programmers write programs to handle a specific job, such as a program to track inventory within an organization. They also may revise existing packaged software or customize generic applications which are frequently purchased from independent software vendors. Systems programmers, in contrast, write programs to maintain and control computer systems software, such as operating systems and database management systems. These workers make changes in the instructions that determine how the network, workstations, and CPU of the system handle the various jobs they have been given and how they communicate with peripheral equipment such as printers and disk drives. Because of their knowledge of the entire computer system, systems programmers often help applications programmers debug, or determine the source of, problems that may occur with their programs.

Types of software

Programmers in software development companies may work directly with experts from various fields to create software — either programs designed for specific clients or packaged software for general use — ranging from computer and video games to educational software to programs for desktop publishing and financial planning. Programming of packaged software constitutes one of the most rapidly growing segments of the computer services industry.

In some organizations, particularly small ones, workers commonly known as programmer analysts are responsible for both the systems analysis and the actual programming work. The transition from a mainframe environment to one that is based primarily on personal computers (PCs) has blurred the once rigid distinction between the programmer and the user. Increasingly, adept end users are taking over many of the tasks previously performed by programmers. For example, the growing use of packaged software, such as spreadsheet and database management software packages, allows users to write simple programs to access data and perform calculations.

In addition, the rise of the Internet has made Web development a huge part of the programming field. More and more software applications nowadays are Web applications that can be used by anyone with a Web browser. Examples of such applications include the Google search service, the Hotmail e-mail service, and the Flickr photo-sharing service.

Globalization of Programming


 The examples and perspective in this article deal primarily with the United States and do not represent a worldwide view of the subject. Please improve this article or discuss the issue on the talk page.

Market Changes in the USA

Computer programming, offshore outsourcing, and Foreign Worker Visas became a controversial topic after the crash of the dot com bubble left many programmers without work or with lower wages. Programming was even mentioned in the 2004 U.S. Presidential debate on the topic of offshore outsourcing.

Large companies claim there is a skills shortage with regard to programming talent. However, U.S. programmers and unions counter that large companies are exaggerating their case in order to obtain cheaper programmers from developing countries and to avoid paying for training in very specific technologies. Objective studies on this debate that both sides accept have been hard to come by and a distrust has formed between large companies and programming trade groups.

Enrollment in computer-related degrees in U.S. has dropped recently due to lack of general interests in science and mathematics and also out of an apparent fear that programming will be subject to the same pressures as manufacturing and agriculture careers. This situation has resulted in confusion about whether the U.S. economy is entering a "post-information age" and the nature of U.S. comparative advantages. Technology and software jobs were supposed to be the replacement for factory and agriculture jobs lost to cheaper foreign labor, but if those are subject to free trade losses, then the nature of the next generation of replacement careers is not clear at this point.

A parallel trend that has made it harder for some programmers to find work in the United States is the ongoing professionalization of computer programming. As software quality has steadily increased in successive years, the knowledge and experience required to produce such software has also increased, particularly as new programming languages, software project management techniques, and application frameworks have been introduced. Programmers who lack an understanding of these new technologies will naturally encounter decreasing demand for their services.

Professionalization is a particularly relevant force in the United States, as startup companies in particular often outsource the development of an initial application draft to an outside contractor (including overseas companies), and then hire a skilled in-house programmer in the United States to refine the initial product.

See also


Look up programmer, coder in Wiktionary, the free dictionary.

References

  1. ^ "No Programmers". http://www.ericsink.com/No_Programmers.html.
  2. ^ "Developer versus programmer". http://codebetter.com/blogs/raymond.lewallen/archive/2005/02/22/55812.aspx.
  3. ^ "Developers AND Programmers". http://weblogs.asp.net/miked/archive/2006/10/13/_2200_Developers_2200_-and-_2200_Programmers_2200_.aspx.
  4. ^ "Programmer vs. Developer vs. Software Engineer". http://discuss.joelonsoftware.com/default.asp?joel.3.112837.37.
  5. ^ "Programmer vs. Developer vs. Software Engineer". http://www.xtremevbtalk.com/archive/index.php/t-233780.html.
  6. ^ J. Fuegi and J. Francis, "Lovelace & Babbage and the creation of the 1843 'notes'." Annals of the History of Computing 25 #4 (Oct-Dec 2003): 19, 25. Digital Object Identifier
  7. ^ ENIAC Programmers Project
  8. ^ ABC News: First Computer Programmers Inspire Documentary
  9. ^ International Programmers' Day

External links

Retrieved from "http://en.wikipedia.org/wiki/Programmer"

Software documentation

From Wikipedia, the free encyclopedia

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.

Types of software documentation

Documentation is an important part of software engineering. Types of documentation include:

  • Requirements - Statements that identify attributes, capabilities, characteristics, or qualities of a system. This is the foundation for what shall 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 APIs.
  • End User - Manuals for the end-user, system administrators and support staff.
  • Marketing - How to market the product and analysis of the market demand.

Requirements documentation

Requirements documentation is the description of what a particular software does or shall fulfill. 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 experts, 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 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. Unfortunately, requirements documentation is therefore very often incomplete or non-existent. The consequence is that changes to the software becomes very difficult and therefore time-consuming (expensive) and error prone (decreased software quality).

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.

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.

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, Sandcastle, ROBODoc, POD , TwinText , or Universal Report 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.

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.

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.

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. 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, Lisp users could look up documentation prepared by these API Writers and paste the associated function directly into their own code. This level of ease of use is unheard of in putatively more modern systems.

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.

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 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] See also

References


 This article does not cite any references or sources. Please help improve this article by adding citations to reliable sources. Unverifiable material may be challenged and removed. (October 2008)

External links

  • kelp - a source code annotation framework for architectural, design and technical documentation
Retrieved from "http://en.wikipedia.org/wiki/Software_documentation"
Subscribe to: Posts (Atom)
Search Engine Submission - AddMe