Das n-doc Verfahren für technische Dokumentation

Die Komplexität eines IT-Systems in einer technischen Dokumentation abzubilden, ist eine Herausforderung in vielen Software-Projekten.

Software und Dokumentation werden meist mit ganz unterschiedlichen Werkzeugen entwickelt, obwohl die Anforderungen sehr ähnlich sind: Versionierte Artefakte, effiziente Verfahren zum Vermeiden von Redundanzen, kollaborative Verfahren und Automatisierung durch Text-Generatoren.

Genau hier setzt das n-doc Verfahren an, um die Erfahrungen, Kenntnisse und Kreativität der Entwickler für die Erstellung von Dokumentation effektiv einzusetzen. Statt „klassischer“ Ansätze der Textverarbeitung mit What-You-See-Is-What-You-Get Programmen nutzt das n-doc Verfahren im Kern das bewährte Textsatzsystem LaTeX. So erstellen Sie typographisch hochwertige Dokumente – immer im Zielformat PDF und dokumentübergreifend im einheitlichen Erscheinungsbild.

  • Koordination der gemeinsamen Arbeit
  • Versionierung sichert Nachvollziehbarkeit
  • Konsistenz in Inhalt und Form

  • Navigation durch generierte Hyperlinks
  • Akzeptanz bei Autorinnen und Autoren
  • Quelloffene Werkzeuge

n-doc ist ein quelloffenes Verfahren und mit unserer Beispielanwendung sofort nutzbar. Unsere erfahrenen Spezialisten unterstützen Sie bei der Einführung und der Entwicklung Ihrer spezifischen Anpassungen.


Open Source

Mit n-doc verwenden Sie ein hoch flexibles und genau auf Ihre Zwecke anpassbares Verfahren. n-design hat ausgehend von den Erfahrungen aus dem Evaluierungsverfahren des Konnektors eine Beispielanwendung entwickelt und im Quellcode auf GitHub veröffentlicht. Die freizügige MIT-Lizenz stellt sicher, dass es für Sie keine Verpflichtung zur Veröffentlichung Ihrer Dokumente oder Anpassungen gibt.

Zum Übersetzen der Dokumente benötigen Sie das n-doc Docker Image. Es enthält alle notwendigen Komponenten zum Übersetzen der Dokumente. Alternativ verwenden Sie eine TeX Installation, die LuaTeX enthält, sowie einige Zusatzpakete für Lua, wie in der Dokumentation beschrieben.


Die n-doc Beispielanwendung ist die Vorlage für Ihr eigenes CC-Verfahren. Das Template zeigt den Anwendungsfall auf der Ebene eines EAL 3+ Verfahrens: Es enthält das Security Target (ASE), die Funktionale Spezifikation (ADV_FSP), die Design Spezifikation (ADV_TDS) und die Testabdeckung (ATE_COV) für einen fiktiven Evaluierungsgegenstand. Der Professional Service von n-design begleitet Sie bei der Einführung des Verfahrens. Bedarfsgerecht und effizient unterstützen wir das Coaching der Mitarbeiter und die Entwicklung von Erweiterungen, die Sie für ihren spezifischen Anwendungsfall brauchen: Zusätzliche Makros und Datenbanktabellen, aber auch Integration des Verfahrens in Ihre Continuous Integration/Delivery Prozesse. n-doc wird bei n-design seit Mitte 2017 kontinuierlich eingesetzt und weiterentwickelt. In unserem Blog erfahren Sie mehr darüber.

Gerne machen wir Ihnen ein Angebot für unsere Dienstleistungen. Sprechen Sie uns an!

Ihre Expertise und unsere Erfahrung
Dokumente wie Software: Mit Werkzeugen, die Entwicklern vertraut sind.

Technische Dokumentation muss zusammen mit der Software geschrieben werden – idealerweise mit Werkzeugen und Methodiken, die den Autoren vertraut sind: Versionsverwaltung mit Git, Build-Chains auf der Basis von GNU Make und die freie Wahl des Editors zeichnen das n-doc Verfahren aus. Ob vi, Emacs, Visual Studio Code oder Eclipse: Wie bei der Erstellung des Programmcodes wählen Entwickler für das Erstellen der Dokumentation ihr präferiertes Werkzeug selbst aus.


In einem Evaluierungsverfahren nach Common Criteria treffen ein komplexer Beschreibungsgegenstand und ein formales Vorgehensmodell aufeinander. Hierbei die Orientierung zu behalten ist eine große Herausforderung. Das n-doc Verfahren setzt auf eine leichtgewichtige in-Memory Datenbank, um die Eigenschaften des Target of Evaluation und die Entitäten des Vorgehensmodells zueinander in Relation zu setzen. Gleichzeitig wird so inhaltliche und formale Konsistenz in den Dokumenten gewährleistet. Die Beiträge im n-design Blog erläutern die Motivation für Entwicklung des Verfahrens und gehen auf technische Details ein.

Von der Text-Formatierung zur domänenspezifischen Dokumentstruktur

Ansprechpartner

DSO
Dominic Sommer
Geschäftsbereichsleiter
+49 (221) 222 896 – 29

Diese Seite benutzt Cookies. Um dem Einsatz von Cookies zuzustimmen klicken Sie bitte auf "OK, ich stimme zu". Weitere Informationen zum Datenschutz erhalten Sie über den folgenden Link: Datenschutzerklärung

The cookie settings on this website are set to "allow cookies" to give you the best browsing experience possible. If you continue to use this website without changing your cookie settings or you click "Accept" below then you are consenting to this.

Close