Technische Standards dokumentieren
Damit Ihr technischer Standard erfolgreich wird
Ihre Organisation entwickelt einen Standard, der andere Unternehmen in Ihrer Branche mit Schnittstellen, Datenbank- und Austauschformaten oder Frameworks unterstützt.
Für die erfolgreiche Anwendung eines Standards ist nicht nur die technische Seite wichtig, sondern auch die Qualität der begleitenden Dokumentation, insbesondere der Spezifikation.
Eine hervorragende Dokumentation kann dazu beitragen, dass sich ein Standard durchsetzt und interoperabel verwendet wird.
Wir dokumentieren Ihren technischen Standard
Wir sind ein erfahrener Dienstleister für die Dokumentation technischer Standards. In der Spezifikation erläutern wir die grundsätzlichen Strukturen Ihres Standards und die Regeln für seine Anwendung. Wir unterscheiden klar zwischen beschreibenden Inhalten, Beispielen und technischen oder fachlichen Regeln, die eine bestimmte Umsetzung erfordern oder ermöglichen. Auf Wunsch erstellen wir Testfallbeschreibungen, um sicherzustellen, dass die Einhaltung dieser Regeln auch automatisiert geprüft werden kann.
Zusätzlich verwenden wir Anwendungsbeispiele, Use-Cases, Tutorials und Code-Beispiele. So entstehen bei der Anwendung des Standards weniger Fragen und Unsicherheiten. So arbeiten wir.
Ihre Ansprechpartner:innen
Dokumentation technischer Standards
Unsere Kundschaft
Dokumentation technischer Standards. So arbeiten wir
- Standard und Zielgruppen kennenlernen. Wir lernen Ihren Standard und seine Zielgruppen kennen.
- Ihre Ziele klären. Wir klären Ihre strategischen Ziele bezüglich Content-Management und Nutzung des Standards und seiner Dokumentation durch die Anwender:innen
- Informationsarchitektur anwenden und anpassen. Wir verwenden unsere bewährte Informationsarchitektur für technische Standards mit Strukturen für Konzepte, Referenzinformationen, Regeln, Use-Cases und Code-Beispielen. Auf Wunsch passen wir die Informationsarchitektur an Ihre Anforderungen an.
- Standard dokumentieren. Gemeinsam mit Ihren Expert:innen dokumentieren wir Ihren technischen Standard auf Englisch oder Deutsch.
- Entwicklung unterstützen. Wir unterstützen die Entwickler:innen bei der Modellierung und technischen Umsetzung der fachlichen Anforderungen, u. a. mit Terminologiearbeit, Review von Code-Dokumentation und Visualisierung.
- Terminologie und Schreibregeln definieren. Wir legen Sprachregeln fest und wenden diese für die Spezifikation an. Wir prüfen Sprache und Terminologie sämtlicher Inhalte Ihrer Spezifikation mit besonderem Fokus auf Konsistenz und Verständlichkeit.
Weitere Informationen rund um das Thema technische Standards finden Sie auch in unseren FAQs.
FAQS – Häufig gestellte Fragen zur Dokumentation technischer Standards
Warum muss man technische Standards dokumentieren?
Eine verständliche und genaue Dokumentation eines technischen Standards ermöglicht es Anwender:innen, die Standards zu verstehen und in ihren eigenen Lösungen umzusetzen.
Standards sind oft mit Sicherheitsaspekten verbunden. Eine genaue Dokumentation stellt sicher, dass die Standards korrekt implementiert werden und dass alle potenziellen Sicherheitsrisiken berücksichtigt werden.
Innerhalb einer Standardisierungsorganisation kann die technische Dokumentation dazu beitragen, Lücken und Interpretationsspielraum im Standard aufzudecken. Sie sorgt auch dafür, dass alle, die an der Erarbeitung des Standards beteiligt sind, dieselbe Sprache sprechen.
Was ist bei der Dokumentation technischer Standards wichtig?
Die folgenden Aspekte gelten für die Dokumentation technischer Standards:
Vollständigkeit
- Enthält alle notwendigen Informationen, um den Standard zu verstehen und anzuwenden.
Klarheit, Aktualität, Konsistenz und Verständlichkeit
- Ist klar und präzise formuliert, um Missverständnisse zu vermeiden. Wichtig sind in diesem Zusammenhang auch die klare Beschreibung von verpflichtenden und optionalen Regeln sowie Empfehlungen. Siehe auch Swagger OpenAPI specification, RFC2119 oder RFC8174.
- Ist aktuell und enthält alle relevanten Änderungen.
- Verwendet eine konsistente Sprache und einheitliche Terminologie.
- Definiert alle wichtigen technischen und sachlichen Konzepte des Standards.
- Ist für die Zielgruppen verständlich.
Anwendbarkeit
- Enthält Beispiele und Use-Cases für die Anwendung in der Praxis.
Zugänglichkeit
- Ist leicht zugänglich, damit Anwender:innen und Expert:innen schnell auf die benötigen Informationen zugreifen können und es keine Hürden bei der Umsetzung gibt.
Was sind gute Beispiele für Dokumentationen technischer Standards?
Hier ist ein Beispiel für die Dokumentation technischer Standards:
- Dokumentation zum CSS Validators des World-Wide-Web-Consortiums (W3C). Die Dokumentation ist bekannt für ihre Verständlichkeit und Anwendbarkeit und enthält Beispiele und Implementierungsanweisungen.