software documentation software documentation is written text or illustration that accompanies computer software or is embedded in the source code it either explains how it operates or how to use it and may mean different things to people in different roles 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 will be or has been implemented architecturedesign 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 enduser 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 do it is used throughout 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 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 comes in a variety of styles notations and formality requirements can be goallike eg distributed work environment close to design eg builds can be started by rightclicking 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 who shall read and use the documentation thus requirements documentation is often incomplete or nonexistent without proper requirements documentation software changes become more difficult and therefore more error prone decreased software quality and timeconsuming 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 eg mobile phone software requirements can help to better communicate what to achieve if the software is safetycritical and can have negative impact on human life eg nuclear power systems medical equipment mechanical equipment more formal requirements documentation is often required if the software is expected to live for only a month or two eg 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 eg using word processing applications and spreadsheet applications to manage the increased complexity and changing nature of requirements documentation and software documentation in general databasecentric systems and specialpurpose requirements management tools are advocated architecture design documentation architecture documentation also known as software architecture description 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 enhanced or not 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 technical documentation technical documentation it is important for the code documents associated with the source code which may include readme files and api documentation to be thorough but not so verbose that it becomes overly timeconsuming or difficult to maintain them various howto and overview documentation guides are commonly 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 endusers using the software application today a lot of highend applications in the field of power energy transportation networks aerospace safety security industry automation and a variety of other domains are seen 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 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 tools such as doxygen ndoc visual expert javadoc eiffelstudio sandcastle robodoc pod twintext or universal report can be used to autogenerate the code documentsthat 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 the idea of autogenerating 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 uptodate 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 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 and coffeescript have builtin 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 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 user documentation unlike code documents user documents simply describe how a program is used in the case of a 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 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 dont need to 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 user documentation can be produced in a variety of online and print formats however 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 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 where the user population is largely correlated with the troubleshooting demands 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 crossreferenced 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 nearexclusion 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 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 1 user analysis the basic research phase of the process 2 planning or the actual documentation phase 3 draft review a selfexplanatory phase where feedback is sought on the draft composed in the previous step 4 usability testing whereby the usability of the document is tested empirically 5 editing the final step in which the information collected in steps three and four is used to produce the final draft documentation and agile development controversy the resistance to documentation among developers is well known and needs no emphasis this situation is particularly prevalent in agile software development because these methodologies try to avoid any unnecessary activities that do not directly bring value specifically the agile manifesto advocates valuing working software over comprehensive documentation which could be interpreted cynically as we want to spend all our time coding remember real programmers dont write documentation 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 eg through reputation systems and gamification may be needed 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 api writer comparison of documentation generators design by contract design document docstring documentation literate programming readme files user assistance unified modeling language uml writeonly documentation notes kelp a source code annotation framework for architectural design and technical documentation automated software documentation application documentation vtesoftware engineeringfields computer programming requirements engineering software deployment software design software maintenance software testing systems analysis formal methods concepts data modeling enterprise architecture functional specification modeling language orthogonality programming paradigm software software archaeology software architecture software configuration management software development methodology software development process software quality software quality assurance software verification and validation structured analysis orientations agile aspectoriented object orientation ontology service orientation sdlc modelsdevelopmental agile eup executable uml incremental model iterative model prototype model rad up scrum spiral model vmodel waterfall model xp other spice cmmi data model er model function model information model metamodeling object model systems model view model languages idef uml usl sysml softwareengineers victor basili kent beck grady booch fred brooks barry boehm peter chen danese cooper ward cunningham tom demarco edsger w dijkstra delores m etter martin fowler adele goldstine margaret hamilton c a r hoare lois haibt mary jean harrold grace hopper watts humphrey michael a jackson ivar jacobson alan kay nancy leveson stephen j mellor bertrand meyer david parnas trygve reenskaug winston w royce james rumbaugh mary shaw peri tarr elaine weyuker niklaus wirth edward yourdon related fields computer science computer engineering project management risk management systems engineering category commons 