The software documentation is a written text which accompanies the software Informatique. She explains how the software functions, or how one must employ it. The term can have significances different for people from various profiles.

Documentation constitutes an important part of the software Ingénierie, which is too often neglected.

Types of documentation

Documentation can be several types:

• Architecture/Design - Overall picture on the software. It includes the relations with environment and the principles to use in the design and the realization of the software components.

• Technical - Documentation of the code, algorithms, interfaces, and Application program interfaces (APIs).
• User - Handbooks for the users, system administrators and personnel of support.
• Marketing - Instructions on the product and promotional guarantee.

Documentation on architecture and the design

Documentation on architecture is a special type of documents of design. In a certain way, the documents on architecture are the third derived ones from the code (documents of design being the second derived ones, and documents on the code being the first). There is very little thing in the documents on the architecture which is specific to the code itself. These documents do not describe how to program a function (routine) particular, or even why this particular function exists in this form, but exposes the general requirements which justify the existence of such a function. A good document of architecture is short on the details but dense on the explanation. It can suggest approaches for design moreover low level, but leaves the effective studies of exploration to other documents.

Another kind of documents of design is the document of comparison. That can often take the form of a White paper . It concentrates on a specific aspect of the system and suggests alternative approaches. That can be at the level of the Interface user, the code, the design, or even on the level of architecture. He will underline the situation of the " SI" (information system), will describe one or more alternives by having their advantages and disadvantages. A good comparative study is heavy seeks, expresses its ideas of them clearly (without resting massively on a Jargon abscon to plug the reader), and especially is impartial. It must explain honestly and clearly the costs of any solution compared to what it brings of better. The objective of a comparative study is to distinguish the best solution, rather than to push from a particular point of view. It is perfectly acceptable not to establish a conclusion, or to conclude that none the alternatives offers of substantial advantage compared to the current location to justify a change. It must be conceived like a scientific initiative, not like a technique marketing.

Technical documentation

Being a question of technical documentation, it is appropriate to distinguish several types of documentation:

• documentation associated with the Operating software , which provides to the owner the instructions of use of the Computer material (Ordinateur);
• documentation associated with the application software (great functions with the company: finances, purchases, logistics,…), which indicates how to use the software.

The majority of the Programmeur S employ the expression " software documentation " in the case of a documentation on the application software . When they develop Logiciel, the Source code is insufficient with him only. There must be text which accompanies it to describe the various aspects of awaited operation. This documentation is usually included in the source code codes itself so that it is easily accessible to whoever would be brought to cross it.

This written document can be highly technical, and it is mainly used to define and explain the Application program interfaces (APIs), the structures of data and the algorithms. For example, one can use this documentation to explain that the variable m_name refers to the first and the last name of a person. It is important for the documents on the code to be precise, but not either verbeux at a point such as it would be difficult to maintain it.

Often, of the tools like Doxygen, Javadoc, ROBODoc, POD gold TwinText can be used automatically to generate the document on the code; they extract the comment from the source code and create handbooks of reference in forms like the text or of the files HTML. The documents on the code are often organized in the style of a guide of reference , which makes it possible a programmer to quickly locate a function or an unspecified class.

Many Programmeur S likes really the idea of generated documentation automatiquemet for various reasons. For example, because it is extracted from the Source code itself (for example, through the comment S), the programmer can write it while referring to his code, and can use the same tools as those which he used to develop the source code, to make documentation. That makes much easier the update of documentation.

Of course, the disadvantage is that only the Programmeur S can publish this kind of documentation, and it is them which the update depends on the exits (for example, by carrying out a Crontab to update the documents the night). Some could characterize that as an advantage rather than like a disadvantage.

Donald Knuth insisted on the fact that documentation can be a very difficult process of reflection afterwards and recommended the Programmation well-read woman, which consists to write documentation at the same time and in the same place as the Source code and to extract it by average automatics.

User's documentation

With the difference of documentation on the code, the documents users are generally rather far away from the source code of the program, and describe simply how it is employed.

In the case of a software Library, the documents on the code and the documents users could be coupled indeed and it is worth to gather them, but that is not always valid for the applications in general.

The Machine Lisp followed the tradition according to which each element of code had an attached field of documentation. In relation to the strong capacities of research (based on a comparable order appropriate to Unix), and sources on line, the users of Lisp could consult documentation and take again the directly associated function in their own code. This level of facility is unknown systems supposed more modern.

Typically, the user's documentation describes each characteristic of the program, and the various stages necessary to call it. A good document user can also go until providing a minitieuse assistance on line. It is very important that the documents users are not confused, and that they are up to date. The documents users do not require to be structured in a particular way, but it is very important that they have a index precise. Coherence and simplicity are also two very invaluable qualities. It is considered that the user's documentation constitutes a contract which specifies what the software must make. See too.

There are three great manners of organizing the user's documentation: ; Tutoriel: It is considered that an approach by Tutoriel is most useful for a new user. In this method the user is guided with each stage of achievement of the particular tasks. ; Set of themes: Pöur an intermediate user, one generally employs an approach Thématique, in which the chapters or sections concentrate on a field of private interest. ; List: The final type of principle of organization is that in which the orders or the tasks are simply listed alphabetically, often via cross indices. This last approach is of a very high interest for advanced users who know exactly which fate of information they seek. An objection universally expressed by the users about software documentation is that it adopts only one of these three approaches other than the two others.

In the case of the Microcomputer S, it is frequent to limit the supply of software documentation to the On line help, which is limited to infrmations of reference on the reference on the orders or the lines of menu. The work of teaching of new users or assistance to users more tested to benefit the best from a program is left with private publicateurs, to whom it developer of the software gives a significant assistance.

Documentation marketing

For much of applications, it is necessary to have promotional materials to encourage occasional observers to spend more time being interested in the product.

This form of documentation has three objectives:

1. To incite the potential users to be interested in the product and to instill the desire to imply itself more in the product.

2. To inform the user on what the product does exactly, so that their waitings are in phase with what they will receive.
3. To explain the position of this product compared to other alternatives.

Good technique of marketing is to provide sentences of Hangs clear and memorable which illustrates the point which one wishes to transmit, and also to stress the interworking of the program with other products.

Tools and methods

Life cycle of the software

• Architecture: Framework of architecture (Framework Zachman, DoDAF, MODAF, AGATE)

• Design: Unified Modeling Language UML, SysML, BPML,…
• Realization: BPEL,…

Software genius and documentation

• Programming well-read woman

Use of the French language

If there is a Contrat with a Consommateur, and for any organization governed by the French law, the Relative law with the use of the French language applies (law commonly called Loi Toubon, 1994).

In 1996, a circular specified that the directions for use of the exploitation and application software were to be written in French.

The licenses of software can be more or less conceived according to the needs for software documentation.

Case of supply of Computer material

The supply of Computer material is usually matched supply of the associated software documentation which indicates to the personnel exploiting the instructions which make it possible to employ the Computer material.

Case of the Free software

License GNU/FDL of Free Software Foundation was thought and created for documentation associated with the Logiciel, it is very largely used for the documentation of the Free software, but not only.

The transfer of rights (concretized by a license) is a contract with the legal direction, the law Toubon applies insofar as the organization is governed by the French law.

For more details: Licenses of the free documents on documentlibre.org

Controls of application of the law

It is the DGCCRF which is charged to carry out controls of application of the law. The Commission of the cultural affairs asks so that a circular can bring “the clarifications necessary to the good application of the law on the use of the French language in the numerical universe”, in particular to be able to reinforce the framework in which must fit controls of the DGCCRF.

See too

• Programming by contract

• Writer of documentation