EP1861796A2

EP1861796A2 - Documentation generation process

Info

Publication number: EP1861796A2
Application number: EP06724953A
Authority: EP
Inventors: Markus Fislage; Christophe Kolb
Original assignee: Robert Bosch GmbH
Current assignee: Robert Bosch GmbH
Priority date: 2005-03-11
Filing date: 2006-03-06
Publication date: 2007-12-05
Also published as: WO2006094966A2; WO2006094966A3; DE102005011247A1; US20080250395A1; CN101156151A

Abstract

A process is disclosed for automatically generating documentation (1, 15) on a project (17). At least one architecture description which reproduces an architecture of the project (17) with individual architecture elements is combined with detailed descriptions (23) of the architecture elements by means of a configuration management tool.

Description

23/02/2006

5

ROBERT BOSCH GMBH, 70442 Stuttgart

0 Procedure for creating a documentation

The invention relates to a method for creating a documentation, a documentation for a project, a computer program and a computer program product for carrying out the method. 5

State of the art

Up-to-date documentation on a software product is particularly important in larger teams that create this software product. With this documentation, a communication overhead, which usually contains more data added to the actual payload, and any misunderstandings that may occur, can be avoided. Providing consistent and comprehensive documentation is currently a problem for a product that has many variants because there is no common tooling or tool that can be used to summarize different aspects of the product and thus provide documentation.

Against this background, a method, a documentation, a computer program and a computer program product with the features of the independent claims are presented. In the method according to the invention for automatically creating a documentation for a project, at least one architectural description representing an architecture of the project with individual architectural elements and detailed descriptions of the architectural elements are combined with a configuration management tool.

This process provides consistent documentation for the project, which can also be a product. In this documentation, the at least one architectural description or at least one o architecture information and detailed descriptions are brought together. Both

Architectural elements may be different software elements such as modules, functions, structs, enums (decision tree methods), APIs (application or programming interfaces), variables, documents, models, design information, file codes, and the like. 5

When creating or developing the product, such as a software product, the software elements change due to changes, revisions and handovers that accompany the development. The software elements can therefore be present as dynamic or non-static files. Each of the software elements of the product may be available in its own version at the time of the o creation. This again reflects that some software elements are to be modified more intensively or more frequently than other software elements.

The configuration management tool may be configured as a tool or program for managing and / or versioning all of the software elements present within the product at different times in different versions. With this configuration management tool, relationships between the software elements may also be organized depending on different versions of at least one specific software element depending on time. To test the product, it is necessary to freeze a full version of the product currently available at a given time. The product is tested in a specific condition that is static at this time. All software elements that are currently available in the latest versions are taken into account. Further future changes and thus versions to be updated are not taken into consideration.

With the configuration management tool, it is thus possible to automatically provide the current documentation adapted to the overall version of the product at the respective time. This is an automatic compilation of design and architectural information that come from different sources or software inventories and in turn are available in different versions. A software element does not necessarily have to use the most up-to-date version; depending on the requirements, an older version may also be better suited for specific requirements. Accordingly, a software element may be present in at least one version within the entire product, with different versions of this software element being interrelated or interacting with different other software elements.

In the method for creating a documentation for a project, in one possible embodiment with a code generator, a frame with at least one architectural description for the project can be generated. The at least one architectural description can be used to represent structural relationships or relationships between architectural elements. Furthermore, it is possible to provide detailed descriptions of individual architectural elements to the project in the

Frame insert.

Furthermore, detailed descriptions may be mixed with one or more architectural descriptions. Hand-editable areas of the documentation can be kept unchanged. - A -

In an embodiment of the method, the detailed descriptions are transmitted from the code generator from a first point of the documentation or the frame to a second position of the documentation or the frame and optionally inserted with minor method change in this second point or 5 merged. For this, the detailed descriptions from the first place are to be cut or copied.

It is also possible to generate templates for detailed descriptions in the method, for example, with the help of the code generator. This makes creating or creating the documentation even easier.

When the procedure is performed, the documentation is automatically generated. It also suggests that the process be accompanied by a development of the project or product. In this case, the documentation can be continuously updated during a development process of the project at least in time or in sections, for example at suitable, stipulated times or after suitable, fixed periods of time. The documentation thus created or generated is adapted to the project and thus always up-to-date or up-to-date.

o The method can provide a versioned and template-compliant document within the documentation for at least one architectural element that is a module. However, it can also for other architectural elements, such. For example, functions, structs, and the like, such documentation may be provided. 5

The method is preferably suitable for the creation of up-to-date documentation of software products. In addition to providing or programming such a software product, the documentation may be prepared. Thus, programmers and developers always have a structured and easily manageable overview of a respective development status of a software project or

Product provided. In the documentation for a project according to the invention, at least one architectural description representing an architecture of the project with individual architectural elements and detailed descriptions of the five architectural elements are automatically merged with a configuration management tool.

This documentation documents detailed descriptions of individual architectural elements of the project. In addition, the documentation shows structural relationships or relationships between individual architectural elements.

The documentation according to the invention for a project is created in the form of a code generator. In this case, a frame with at least one architectural description of the project, for example, can be generated by this code generator, wherein the detailed descriptions of individual architectural elements are added to the project in the frame.

With this documentation it is possible to document detailed descriptions of individual 20 architectural elements of the project, which may also be a product.

The documentation is preferably based on the HTML format or any other suitable application in a graphical or illustrative environment.

25

The procedure can be carried out accompanying the project, so that the documentation is created during the project. The project can be under version control. The invention provides a uniform tooling that combines both architecture and detailed software descriptions. A relationship between architecture and design is transient. Thus, an automatic generation of a unified document, whereby a detail in the software can be changed without affecting the architecture.

Projects designed as complex and sophisticated software landscapes are generated separately by the at least one architectural description and many detailed descriptions of individual modules. In doing so, an architecture for the project or product is developed, for example by means of a UML tool, and, if necessary, code is also generated. With such a generation, an existing implementation can be maintained. In parts, the same information from the at least one architectural description is repeated in the detailed documentation for the software, thus describing the context and interfaces. The architecture can be regularly project-spanned and therefore does not necessarily have to be different between different projects. Architectural elements, e.g. Software modules, on the other hand, almost always differ from project to project. Therefore, detailed descriptions are set up together with a code by means of MKS, ClearCase, as an example of a configuration management tool, cvs, and the like in a version control system.

With the method according to the invention and the documentation according to the invention, the at least one architectural description and the detailed one are or will be

Descriptions automatically merged. In complex software environments, a large number of combinations between architectural and module variants or versions is common. All these combinations are considered dynamically in the automatically generated documentation. Ideally, the documentation will be compiled from all module versions and the architecture currently in use. A user of the documentation can easily orient himself on the clearly structured architecture and thus "hang along", which leads him to a desired information or detailed description. Within the documentation it is possible to access specific APIs, enums, variables or other architectural elements by mouse click and search functions. The documentation is because of the automatic generation always up to date. There is a consistent single source concept for the documentation.

The project or product may also be a complex system, such as a motor vehicle or an electromechanical device having various different functions. Such systems usually consist of a plurality of interacting components or modules. With the method according to the invention, a development and a production of the system can be accompanied. It is also conceivable to provide an operating or operating manual based on the documentation o for this system.

The computer program with program code means according to the invention is designed to carry out all steps of the method according to the invention when this computer program is carried out on a computer or a corresponding computer unit.

The computer program product according to the invention with program code means which are stored on a computer-readable data carrier is intended to carry out all the steps of the method according to the invention when the computer program is executed on a computer or a corresponding computer unit.

Further advantages and embodiments of the invention will become apparent from the description and the accompanying drawings. 5

It is understood that the features mentioned above and those yet to be explained below can be used not only in the respectively specified combination but also in other combinations or alone, without departing from the scope of the present invention. 0 The invention is illustrated schematically by means of embodiments in the drawing and will be described in detail below with reference to the drawing.

Figure 1 shows a schematic representation of a first embodiment of a

Documentation with individual components.

Figure 2 shows a schematic representation of a preferred embodiment of a description of a module.

Figure 3 shows a schematic representation of another embodiment of a

Documentation.

FIG. 4 shows a schematic diagram of a preferred implementation of a method.

FIG. 1 shows a schematic representation of a first embodiment of a documentation 1 embedded in a user interface. It is envisaged that this documentation 1 results in a construction in a possible variant of the method according to the invention from a plurality of components 3, 5, 7, 9. It flows one

Project selection 3 in the documentation 1. Detailed descriptions 9 are provided by a MKS library in the present first embodiment. Furthermore, a QRP script 5 is provided, with which it is possible to generate diagrams and reference lists for diagrams. With a C code generator 7 as a component of a C compiler, for example an ACD code generator, a design for the documentation 1 is created.

The result in this case is documentation 1 in HTML format. For each architectural element or module, a versioned and template-compliant document is available, from which detailed descriptions 9 are introduced into the final documentation 1. In this case, the detailed ones Descriptions 9 also HTML based. Regions within the documentation 1 that are to be edited are marked accordingly and uniquely provided with identifiers that assign specific information to a respective architectural element. These identifiers are hidden behind HTML comments in this embodiment. Thus, from an architectural model, a template can be created, which is a

Author or programmer, where additional detailed descriptions 9 or information should be entered during the creation of a project or product for which documentation 1 is intended.

Figure 2 shows a schematic representation of an embodiment of a

Architectural element formed as a module 11. Here, a description of this module 11 oss ind interruptdispatcher is required. This description must be made between the cursive text "Manual Edit Section" and "Manual Edit Section End - do not remove". Such areas are e.g. influenced by a function. Details or information are not yet sufficiently entered in an associated template.

In a definitive documentation 13, which in one possible embodiment is shown schematically in FIG. 3, the detailed description is then introduced into a fully linked page, which relates to a respective module.

In this case the detailed description is not filled out yet. All elements that can be integrated via HTML, such as images, animations and the like, can be used. The embedded page is not just a template, it also includes links and dynamic architectural descriptions.

Such documentation 13, which includes architectural and detail descriptions, can be provided to programmers and writers, as well as future users of a product or system, ie, customers. In a landscape that is out different projects and their versions, the process is an automated process for providing documentation.

FIG. 4 shows a schematic representation of a diagram for the procedure of a method for producing a documentation 15 for a project 17, in which a

Architectural description that reflects architecture to the single architectural element project 17 and detailed descriptions 23 of individual architectural elements are assembled to the product 17.

In this variant for generating the documentation 15, at least partially a code generator 19 is used with which a frame 21 for the architectural description is created and detailed descriptions are inserted into this frame. The code generator 19 makes it possible to retain attributable areas and to intermix descriptive fragments from another site with a slight change of method. In this case, the frame 21 is generated with all the architectural descriptions. Detailed descriptions of the architecture elements such as modules, functions, APIs, structs, enums are included in detailed documents. The templates for the detailed descriptions are also generated. The documentation 15 created in this way is individually adapted to the project 17 and is always up-to-date.

The method can be used, for example, in a project 17, product or system for a motor vehicle application, wherein a number of control devices, for example for an airbag, interact with one another. The documentation produced by the method may also accompany a development of a complex system, such as a motor vehicle having many individual components. Based on the documentation, a user manual is to be made available to a future user of the system.

Claims

23.02.2006ROBERT BOSCH GMBH, 70442 StuttgartApprovals

A method of automatically creating a documentation (1, 13, 15) for a project (17) in which at least one architectural description representing an architecture of the single architectural element project (17) and detailed descriptions (9, 23) are provided the architectural elements are merged with a configuration management tool.

2. The method of claim 1, wherein a frame (21) is generated with the at least one architectural description of the project (17).

A method according to claim 1 or 2, which accompanies development of the project (17).

4. The method according to any one of the preceding claims, are maintained in the attributable areas of the documentation (1, 13, 15).

5. The method according to any one of the preceding claims, wherein the detailed descriptions from a first location in a second position of the documentation (1, 13, 15) are inserted.

6. Method according to one of the preceding claims, in which templates for the detailed descriptions (9, 23) are generated.

7. The method according to any one of the preceding claims, wherein for each architectural element, which is designed as a module (11), a versioned and template conforming document is provided.

8. Documentation on a project (17) in which at least one architectural description representing an architecture of the project (17) with individual architectural elements and detailed descriptions (9, 23) of the architectural elements are automatically merged with a configuration management tool.

Documentation according to claim 8, which documents detailed descriptions (9, 23) of individual architectural elements of the project (17).

10. Documentation according to claim 8 or 9, are reproduced by the relationships between individual architectural elements.

Documentation according to one of claims 8 to 10, based on the HTML format.

A computer program comprising program code means for performing all the steps of a method according to any one of claims 1 to 7 when the computer program is executed on a computer or a corresponding computing unit.

A computer program product comprising program code means stored on a computer readable medium for carrying out all the steps of a method as claimed in any one of claims 1 to 7 when the computer program is run on a computer or a corresponding computing unit.