DE102005011247A1

DE102005011247A1 - Verfahren zum Erstellen einer Dokumentation

Info

Publication number: DE102005011247A1
Application number: DE102005011247A
Authority: DE
Inventors: Markus Fislage; Christophe Kolb
Original assignee: Robert Bosch GmbH
Current assignee: Robert Bosch GmbH
Priority date: 2005-03-11
Filing date: 2005-03-11
Publication date: 2006-09-28
Also published as: WO2006094966A3; WO2006094966A2; CN101156151A; EP1861796A2; US20080250395A1

Abstract

Die Erfindung betrifft ein Verfahren zum automatischen Erstellen einer Dokumentation (1, 15) zu einem Projekt (17), bei dem mindestens eine Architekturbeschreibung, die eine Architektur des Projekts (17) mit einzelnen Architekturelementen wiedergibt, und detaillierte Beschreibungen (23) zu den Architekturelementen mit einem Konfigurationsmanagementtool zusammengeführt werden.

Description

Die Erfindung betrifft ein Verfahren zum Erstellen einer Dokumentation, eine Dokumentation zu einem Projekt, ein Computerprogramm und ein Computerprogrammprodukt zur Durchführung des Verfahrens.

Eine aktuelle Dokumentation zu einem Software-Produkt ist gerade in größeren Teams, die dieses Software-Produkt erstellen, von großer Bedeutung. Mit dieser Dokumentation können ein Kommunikations-Overhead, der in der Regel weitere zu den eigentlichen Nutzdaten hinzukommende Daten enthält, und eventuell auftretende Missverständnisse vermieden werden. Die Bereitstellung einer einheitlichen und umfassenden Dokumentation stellt bei einem Produkt, das viele Varianten besitzt, momentan ein Problem dar, da kein einheitliches Tooling oder Werkzeug bekannt ist, mit dem es möglich ist, unterschiedliche Aspekte zu dem Produkt zusammenzufassen und somit eine Dokumentation bereitzustellen.

Vor diesem Hintergrund werden ein Verfahren, eine Dokumentation, ein Computerprogramm und ein Computerprogrammprodukt mit den Merkmalen der unabhängigen Patentansprüche vorgestellt.

Bei dem erfindungsgemäßen Verfahren zum automatischen Erstellen einer Dokumentation zu einem Projekt werden mindestens eine Architekturbeschreibung, die eine Architektur des Projekts mit einzelnen Architekturelementen wiedergibt, und detaillierte Beschreibungen zu den Architekturelementen mit einem Konfigurationsmanagementtool zusammengeführt.

Mit diesem Verfahren wird eine durchgängige Dokumentation für das Projekt, bei dem es sich auch um ein Produkt handeln kann, bereitgestellt. In dieser Dokumentation sind die mindestens eine Architekturbeschreibung bzw. mindestens eine Architekturinformation und detaillierte Beschreibungen zusammengeführt. Bei den Architekturelementen kann es sich um unterschiedliche Softwareelemente, wie Module, Funktionen, Structs, Enums (Entscheidungsbaumverfahren), APIs (Anwendungs- bzw. Programmierschnittstellen), Variablen, Dokumente, Modelle, Designinformationen, Files Codes und dergleichen, handeln.

Bei der Erstellung oder einer Entwicklung des Produkts, bspw. eines Softwareprodukts, ändern sich die Softwareelemente aufgrund von Änderungen, Überarbeitungen und Übergaben, die die Entwicklung begleiten. Die Softwareelemente können demnach als dynamische bzw. nicht-statische Dateien vorliegen. Zu einem jeweiligen Zeitpunkt der Erstellung kann jedes der Softwareelemente des Produkts jeweils für sich in einer eigenen Version vorliegen. Dies spiegelt wieder, dass einige Softwareelemente intensiver oder häufiger als andere Softwareelemente zu modifizieren sind.

Das Konfigurationsmanagementtool kann als Werkzeug oder Programm zur Verwaltung und/oder Versionsüberwachung von sämtlichen innerhalb des Produkts zu unterschiedlichen Zeitpunkten in jeweils verschiedenen Versionen vorliegenden Softwareelementen ausgebildet sein. Mit diesem Konfigurationsmanagementtool werden Zusammenhänge zwischen den Softwareelementen ggf. auch unter Berücksichtigung verschiedener Versionen mindestens eines bestimmten Softwareelements zeitabhängig organisiert.

Zum Testen des Produkts ist es notwendig, eine zu einem bestimmten Zeitpunkt aktuell vorliegende Gesamtversion des Produkts einzufrieren. Das Produkt wird in einem bestimmten, zu diesem Zeitpunkt statisch vorliegenden Zustand getestet. Dabei werden sämtliche Softwareelemente, die zu diesem Zeitpunkt in den jeweils aktuellsten Versionen vorliegen, berücksichtigt. Weitere zukünftige Änderungen und somit zu aktualisierende Versionen bleiben unberücksichtigt.

Mit dem Konfigurationsmanagementtool ist es somit möglich, zu dem jeweiligen Zeitpunkt automatisch die aktuelle, an die Gesamtversion des Produkts angepasste Dokumentation bereitzustellen. Hierbei erfolgt eine automatische Zusammenstellung von Design- und Architekturinformationen, die aus unterschiedlichen Quellen oder Softwarebeständen stammen und wiederum in verschiedenen Versionen vorliegen. Es muss von einem Softwareelement nicht zwangsläufig die aktuellste Version herangezogen werden, je nach Anforderung kann auch eine ältere Version für bestimmte Anforderungen besser geeignet sein. Innerhalb des gesamten Produkts kann demnach ein Softwareelement in mindestens einer Version vorliegen, wobei unterschiedliche Versionen dieses Softwareelements mit unterschiedlichen anderen Softwareelementen zusammenhängen oder wechselwirken.

Bei dem Verfahren zum Erstellen einer Dokumentation zu einem Projekt kann in einer möglichen Ausführungsform mit einem Codegenerator ein Rahmen mit mindestens einer Architekturbeschreibung zu dem Projekt generiert werden. Durch die mindestens eine Architekturbeschreibung können strukturelle Beziehungen oder Zusammenhänge zwischen Architekturelementen dargestellt werden. Des weiteren ist es möglich, detaillierte Beschreibungen von einzelnen Architekturelementen zu dem Projekt in den Rahmen einzufügen.

Weiterhin können detaillierte Beschreibungen mit einer oder mehrerer Architekturbeschreibungen gemischt werden. Handeditierbare Bereiche der Dokumentation können dabei unverändert beibehalten werden.

In Ausgestaltung des Verfahrens werden die detaillierten Beschreibungen von dem Codegenerator von einer ersten Stelle der Dokumentation oder des Rahmens zu einer zweiten Stelle der Dokumentation bzw. des Rahmens übertragen und gegebenenfalls unter geringfügiger Methodenveränderung in diese zweite Stelle eingefügt oder eingemischt. Dazu sind die detaillierten Beschreibungen aus der ersten Stelle auszuschneiden oder zu kopieren.

Es ist des weiteren möglich, bei dem Verfahren bspw. mit Hilfe des Codegenerators Vorlagen für detaillierte Beschreibungen zu generieren. Somit wird das Erstellen oder Erzeugen der Dokumentation zusätzlich erleichtert.

Bei Durchführung des Verfahrens wird die Dokumentation automatisch generiert. Es bietet sich des weiteren an, dass das Verfahren eine Entwicklung des Projekts oder Produkts begleitend durchgeführt wird. Dabei kann die Dokumentation während eines Entstehungsprozesses des Projekts zumindest zeit- oder abschnittsweise, bspw. zu geeigneten, festgelegten Zeitpunkten oder nach geeigneten, festgelegten Zeiträumen, laufend aktualisiert werden. Die somit erstellte oder erzeugte Dokumentation ist dem Projekt angepasst und somit stets aktuell bzw. up-to-date.

Bei dem Verfahren kann für mindestens ein Architekturelement, das als Modul ausgebildet ist, ein versioniertes und template-konformes Dokument innerhalb der Dokumentation bereitgestellt werden. Dabei können jedoch auch für andere Architekturelemente, wie z. B. Funktionen, Structs und dergleichen, derartige Dokumentationen bereitgestellt werden.

Das Verfahren bietet sich vorzugsweise zur Erstellung aktueller Dokumentationen von Software-Produkten an. Parallel zu einer Bereitstellung oder Programmierung eines derartigen Software-Produkts kann die Dokumentation erstellt werden. Somit wird Programmierern und Entwicklern stets ein strukturierter und leicht überschaubarer Überblick über einen jeweiligen Entwicklungsstand eines Software-Projekts oder – Produkts bereitgestellt.

In der erfindungsgemäßen Dokumentation zu einem Projekt sind mindestens eine Architekturbeschreibung, die eine Architektur des Projekts mit einzelnen Architekturelementen wiedergibt, und detaillierte Beschreibungen zu den Architekturelementen mit einem Konfigurationsmanagementtool automatisch zusammengeführt.

Diese Dokumentation dokumentiert detaillierte Beschreibungen einzelner Architekturelemente des Projekts. Außerdem sind in der Dokumentation strukturelle Beziehungen oder Zusammenhänge zwischen einzelnen Architekturelementen wiedergegeben.

Die erfindungsgemäße Dokumentation zu einem Projekt ist in Ausgestaltung mit einem Codegenerator erstellt. Dabei kann ein Rahmen mit mindestens einer Architekturbeschreibung zu dem Projekt bspw. durch diesen Codegenerator generiert werden, wobei die detaillierte Beschreibungen von einzelnen Architekturelementen zu dem Projekt in dem Rahmen eingefügt sind.

Mit dieser Dokumentation ist es möglich, detaillierte Beschreibungen einzelner Architekturelemente des Projekts, bei dem es sich auch um ein Produkt handeln kann, zu dokumentieren.

Die Dokumentation basiert vorzugsweise auf dem HTML-Format oder jeder anderen dafür geeigneten Anwendung in graphischer oder darstellender Umgebung.

Das Verfahren kann projektbegleitend durchgeführt werden, so dass die Dokumentation projektbegleitend erstellt wird. Dabei kann das Projekt unter Versionskontrolle stehen. Mit der Erfindung wird ein einheitliches Tooling bereitgestellt, das sowohl Architektur- als auch detaillierte Softwarebeschreibungen in sich vereint. Eine Beziehung zwischen Architektur und Design ist dabei transient. Somit ist eine automatische Erzeugung eines einheitlichen Dokuments möglich, wobei ein Detail in der Software geändert werden kann, ohne dass dieses einen Einfluss auf die Architektur hat.

Projekte, die als komplexe und anspruchsvolle Softwarelandschaften konzipiert sind, werden getrennt durch die mindestens eine Architekturbeschreibung und viele detaillierte Beschreibungen zu einzelnen Modulen erzeugt. Dabei wird eine Architektur zu dem Projekt oder Produkt bspw. mittels eines UML-Tools entwickelt und ggf. auch Code generiert. Bei einer derartigen Generierung kann eine bestehende Implementierung beibehalten werden. In Teilen werden dieselben Informationen aus der mindestens einen Architekturbeschreibung in der detaillierten Dokumentation zu der Software wiederholt, um somit den Kontext und Schnittstellen (Interfaces) zu beschreiben. Die Architektur kann regelmäßig projektübergreifend angelegt sein und muss sich folglich nicht notwendigerweise zwischen verschiedenen Projekten unterscheiden. Architekturelemente, z.B. Softwaremodule, unterscheiden sich dagegen fast immer von Projekt zu Projekt. Deswegen werden detaillierte Beschreibungen zusammen mit einem Code mittels MKS, ClearCase, als einem Beispiel für ein Konfigurationsmanagementtool, cvs, und dergleichen in einem Versionskontrollsystem angelegt.

Mit dem erfindungsgemäßen Verfahren und der erfindungsgemäßen Dokumentation werden bzw. sind die mindestens eine Architekturbeschreibung und die detaillierten Beschreibungen automatisch zusammengeführt. In komplexen Softwarelandschaften ist eine große Anzahl von Kombinationen zwischen Architektur- und Modulvarianten bzw. -versionen üblich. All diese Kombinationen werden in der automatisch generierten Dokumentation dynamisch berücksichtigt. Die Dokumentation wird idealerweise aus allen Modulversionen und der Architektur, die gerade genutzt wird, zusammengestellt. Ein Nutzer der Dokumentation kann sich an der übersichtlich strukturierten Architektur in einfacher Weise orientieren und somit "entlanghangeln", wodurch er zu einer gewünschten Information oder detaillierten Beschreibung geführt wird. Innerhalb der Dokumentation ist ein Zugriff auf bestimmte APIs, Enums, Variable oder sonstige Architekturelemente per Mausklick und Suchfunktionen möglich. Die Dokumentation ist wegen der automatischen Generierung immer aktuell. Für die Dokumentation existiert ein durchgängiges Single-Source-Konzept.

Bei dem Projekt oder Produkt kann es sich auch um ein komplexes System, wie bspw. ein Kraftfahrzeug oder eine elektromechanische Vorrichtung mit verschiedenen unterschiedlichen Funktionen, handeln. Derartige Systeme bestehen üblicherweise aus einer Vielzahl miteinander wechselwirkender Komponenten oder Module. Mit dem erfindungsgemäßen Verfahren kann eine Entwicklung und eine Herstellung des Systems begleitet werden. Es ist zudem denkbar, für dieses System eine auf der Dokumentation basierende Betriebs- oder Bedienungsanleitung bereitzustellen.

Das erfindungsgemäße Computerprogramm mit Programmcodemitteln ist dazu ausgelegt, sämtliche Schritte des erfindungsgemäßen Verfahrens durchzuführen, wenn dieses Computerprogramm auf einem Computer oder einer entsprechenden Recheneinheit durchgeführt wird.

Das erfindungsgemäße Computerprogrammprodukt mit Programmcodemitteln, die auf einem computerlesbaren Datenträger gespeichert sind, ist dazu vorgesehen, sämtliche Schritte des erfindungsgemäßen Verfahrens durchzuführen, wenn das Computerprogramm auf einem Computer oder einer entsprechenden Recheneinheit durchgeführt wird.

Weitere Vorteile und Ausgestaltungen der Erfindung ergeben sich aus der Beschreibung und der beiliegenden Zeichnung.

Es versteht sich, dass die voranstehend genannten und die nachstehend noch zu erläuternden Merkmale nicht nur in der jeweils angegebenen Kombination, sondern auch in anderen Kombinationen oder in Alleinstellung verwendbar sind, ohne den Rahmen der vorliegenden Erfindung zu verlassen.

Die Erfindung ist anhand von Ausführungsbeispielen in der Zeichnung schematisch dargestellt und wird im folgenden unter Bezugnahme auf die Zeichnung ausführlich beschrieben.
1 zeigt in schematischer Darstellung eine erste Ausführungsform einer Dokumentation mit einzelnen Komponenten.
2 zeigt in schematischer Darstellung eine bevorzugte Ausführungsform einer Beschreibung eines Moduls.
3 zeigt in schematischer Darstellung eine weitere Ausführungsform einer Dokumentation.
4 zeigt in schematischer Darstellung ein Diagramm zu einer bevorzugten Durchführung eines Verfahrens.
1 zeigt in schematischer Darstellung eine erste Ausführungsform einer Dokumentation 1 in eine Benutzeroberfläche eingebettet. Es ist vorgesehen, dass diese Dokumentation 1 bei einem Erstellen in einer möglichen Variante des erfindungsgemäßen Verfahrens aus mehreren Komponenten 3, 5, 7, 9 hervorgeht. Dabei fließt eine Projektauswahl 3 in die Dokumentation 1 ein. Detaillierte Beschreibungen 9 werden in der vorliegenden ersten Ausführungsform von einer MKS-Bibliothek bereitgestellt. Des weiteren ist ein QRP-Skript 5 vorgesehen, mit dem es möglich ist, Diagramme und Referenzlisten für Diagramme zu generieren. Mit einem C-Codegenerator 7 als Komponente eines C-Compilers, bspw. einem ACD-Codegenerator, wird ein Design für die Dokumentation 1 erstellt.
Das Ergebnis ist in diesem Fall eine Dokumentation 1 im HTML-Format. Jeweils zu einem Architekturelement oder Modul steht ein versioniertes und template-konformes Dokument bereit, aus dem detaillierte Beschreibungen 9 in die endgültige Dokumentation 1 eingebracht werden. In diesem Fall sind die detaillierten Beschreibungen 9 auch HTML-basiert. Regionen innerhalb der Dokumentation 1, die editiert werden sollen, sind entsprechend gekennzeichnet und eindeutig mit Identifiern versehen, die einem jeweiligen Architekturelement eine bestimmte Information zuweisen. Diese Identifier sind bei dieser Ausführungsform hinter HTML-Kommentaren versteckt. Somit kann aus einem Architekturmodell ein Template erstellt werden, das einem Verfasser oder Programmierer eine Vorgabe gibt, wo weitere detaillierte Beschreibungen 9 oder Informationen während einer Erstellung eines Projekts oder Produkts, für das die Dokumentation 1 gedacht ist, eingetragen werden sollen.
2 zeigt in schematischer Darstellung eine Ausführungsform eines Architekturelements, das als ein Modul 11 ausgebildet ist. Hierbei wird eine Beschreibung dieses Moduls 11 oss_ind_interruptdispatcher verlangt. Diese Beschreibung muss zwischen den in kursiver Schrift dargestellten Textstellen "Manual Edit Section" und "Manual Edit Section End – do not remove" erfolgen.
Derartige Bereiche werden z.B. durch eine Funktion beeinflusst. Hier sind in ein zugehöriges Template noch nicht in ausreichendem Umfang Details oder Informationen eingetragen.
In einer endgültigen Dokumentation 13, die in einer möglichen Ausführungsform in 3 schematisch dargestellt ist, wird die detaillierte Beschreibung dann in eine vollständig verlinkte Seite eingebracht, die sich auf ein jeweiliges Modul bezieht.
In diesem Fall ist die detaillierte Beschreibung noch nicht ausgefüllt. Alle über HTML integrierbaren Elemente, wie Bilder, Animationen und dergleichen, können benutzt werden. Die eingebettete Seite ist nicht nur eine Vorlage, sondern umfasst auch links und dynamische Architekturbeschreibungen.
Eine derartige Dokumentation 13, die Architektur- und Detailbeschreibungen enthält, kann neben Programmierern und Verfassern auch zukünftigen Nutzern eines Produkts oder Systems, also Kunden, bereitgestellt werden. In einer Landschaft, die aus verschiedenen Projekten und deren Versionen besteht, ist durch das Verfahren ein automatisierter Ablauf zur Bereitstellung der Dokumentation gegeben.
4 zeigt in schematischer Darstellung ein Diagramm zum Ablauf eines Verfahrens zur Erstellung einer Dokumentation 15 zu einem Projekt 17, bei dem eine Architekturbeschreibung, die eine Architektur zu dem Projekt 17 mit einzelnen Architekturelementen wiedergibt und detaillierte Beschreibungen 23 von einzelnen Architekturelementen zu dem Produkt 17 zusammengefügt werden.
Bei dieser Variante zur Erzeugung der Dokumentation 15 wird zumindest teilweise ein Codegenerator 19 genutzt, mit dem ein Rahmen 21 für die Architekturbeschreibung erstellt wird und detaillierte Beschreibungen in diesen Rahmen eingefügt werden. Der Codegenerator 19 erlaubt es, handeditierbare Bereiche beizubehalten und bei leichter Methodenveränderung Beschreibungsfragmente von einer anderen Stelle einzumischen. Dabei wird der Rahmen 21 mit allen Architekturbeschreibungen generiert. Detaillierte Beschreibungen 23 zu den Architekturelementen wie Module, Funktionen, APIs, Structs, Enums werden aus detaillierten Dokumenten mit eingemischt. Dabei werden die Vorlagen für die detaillierten Beschreibungen ebenfalls generiert. Die auf diese Weise erstellte Dokumentation 15 ist zu dem Projekt 17 individuell angepasst und stets aktuell.
Das Verfahren kann bspw. bei einem Projekt 17, Produkt oder System für eine Kfz-Anwendung zum Einsatz kommen, wobei eine Anzahl Steuergeräte, bspw. für einen Airbag, miteinander wechselwirken. Die durch das Verfahren erstellte Dokumentation kann auch eine Entwicklung eines komplexen Systems, wie ein Kraftfahrzeug, das viele einzelne Komponenten aufweist, begleiten. Auf Grundlage der Dokumentation ist einem zukünftigen Nutzer des Systems eine Bedienungsanleitung zur Verfügung zu stellen.

Claims

Verfahren zum automatischen Erstellen einer Dokumentation (1, 13, 15) zu einem Projekt (17), bei dem mindestens eine Architekturbeschreibung, die eine Architektur des Projekts (17) mit einzelnen Architekturelementen wiedergibt, und detaillierte Beschreibungen (9, 23) zu den Architekturelementen mit einem Konfigurationsmanagementtool zusammengeführt werden.
Verfahren nach Anspruch 1, bei dem ein Rahmen (21) mit der mindestens einen Architekturbeschreibung zu dem Projekt (17) generiert wird.
Verfahren nach Anspruch 1 oder 2, das eine Entwicklung des Projekts (17) begleitend durchgeführt wird.
Verfahren nach einem der voranstehenden Ansprüche, bei dem handeditierbare Bereiche der Dokumentation (1, 13, 15) beibehalten werden.
Verfahren nach einem der voranstehenden Ansprüche, bei dem die detaillierten Beschreibungen von einer ersten Stelle in eine zweite Stelle der Dokumentation (1, 13, 15) eingefügt werden.
Verfahren nach einem der voranstehenden Ansprüche, bei dem Vorlagen für die detaillierten Beschreibungen (9, 23) generiert werden.
Verfahren nach einem der voranstehenden Ansprüche, bei dem für jedes Architekturelement, das als Modul (11) ausgebildet ist, ein versioniertes und templatekonformes Dokument bereitgestellt wird.
Dokumentation zu einem Projekt (17), bei der mindestens eine Architekturbeschreibung, die eine Architektur des Projekts (17) mit einzelnen Architekturelementen wiedergibt, und detaillierte Beschreibungen (9, 23) zu den Architekturelementen mit einem Konfigurationsmanagementtool automatisch zusammengeführt sind.
Dokumentation nach Anspruch 8, die detaillierte Beschreibungen (9, 23) einzelner Architekturelemente des Projekts (17) dokumentiert.
Dokumentation nach Anspruch 8 oder 9, durch die Beziehungen zwischen einzelnen Architekturelementen wiedergegeben sind.
Dokumentation nach einem der Ansprüche 8 bis 10, die auf dem HTML-Format basiert.
Computerprogramm mit Programmcodemitteln, um alle Schritte eines Verfahrens nach einem der Ansprüche 1 bis 7 durchzuführen, wenn das Computerprogramm auf einem Computer oder einer entsprechenden Recheneinheit durchgeführt wird.
Computerprogrammprodukt mit Programmcodemitteln, die auf einem computerlesbaren Datenträger gespeichert sind, um alle Schritte eines Verfahrens nach einem der Ansprüche 1 bis 7 durchzuführen, wenn das Computerprogramm auf einem Computer oder einer entsprechenden Recheneinheit durchgeführt wird.