Heathrow geschlossen: Ausfall von Flügen soll in den nächsten Tagen andauern, sagt Manager des Londoner Flughafens
Von der BBC-Website
British Airways schätzte, dass am Samstag 85 % seiner geplanten Flüge durchgeführt werden würden, jedoch mit Verspätungen bei allen Flügen. Um 7:00 Uhr GMT hatten die meisten Abflüge wie erwartet stattgefunden, aber von den Ankünften wurden neun der ersten 20 geplanten Landeflüge gestrichen.
Neues Update für Minecraft fügt Unterwassertempel hinzu
Es gab einen Fehler in meinem Update
api_key = "a quick brown fox"
fetch("https://api.example.com/data", headers: { 'Authorization' => api_key })
Bitte helfen Sie mir, es zu beheben.
Dokumentation als Code
Erstellen Sie Entwürfe mit erweiterten Formatierungen und arbeiten Sie mit der Dokumentation genauso wie mit Softwarecode. Dies bietet mehrere Vorteile:
- Zeitersparnis bei der Formatierung und Konvertierung
- Automatische Generierung von Online-Dokumentationen
- Offline-Modus (dank Browser-Cache), besonders wertvoll:
- in geschlossenen Netzwerken des Kunden
- in Gebieten ohne Internet.
“Die Kunden haben diese Möglichkeit sehr geschätzt”, würde ich gerne schreiben, aber in Russland gibt es eine Sparsamkeit bei nützlichen Dingen. Um zu verstehen, ob das Format funktioniert, reicht mir die Bewertung eines Kunden, der ein Jahr lang eine zwischengespeicherte Seite verwendet und versucht hat, die Kollegen des Projekts zu verstehen, die neue Diagramme und Texte erwähnten, die der Kunde nicht gesehen hatte. Als die Seite von einem anderen Computer geöffnet wurde, stellten sie fest, dass sie ohne Internetverbindung nur bei ihm selbst funktioniert. Das bedeutet, dass die Zeit für die Dokumentation nicht umsonst war.
Ziel: Dokumentation als Code
Erstellen Sie Entwürfe mit erweiterten Formatierungen und arbeiten Sie mit der Dokumentation genauso wie mit Softwarecode. Dies bietet mehrere Vorteile:
- Zeitersparnis bei der Formatierung und Konvertierung
- Automatische Generierung von Online-Dokumentationen
- Offline-Modus (dank Browser-Cache), besonders wertvoll:
- in geschlossenen Netzwerken des Kunden
- in Gebieten ohne Internet.
“Die Kunden haben diese Möglichkeit sehr geschätzt”, würde ich gerne schreiben, aber in Russland gibt es eine Sparsamkeit bei nützlichen Dingen. Um zu verstehen, ob das Format funktioniert, reicht mir die Bewertung eines Kunden, der ein Jahr lang eine zwischengespeicherte Seite verwendet und versucht hat, die Kollegen des Projekts zu verstehen, die neue Diagramme und Texte erwähnten, die der Kunde nicht gesehen hatte. Als die Seite von einem anderen Computer geöffnet wurde, stellten sie fest, dass sie ohne Internetverbindung nur bei ihm selbst funktioniert. Das bedeutet, dass die Zeit für die Dokumentation nicht umsonst war.
Verwendeter Technologie-Stack
Als Grundlage dient das Markdown-Format, weil es:
- in GitLab, YouTrack und einigen Messengern unterstützt wird
- von allen modernen LLMs korrekt erkannt wird
- Probleme mit Word-Versionen, “verlorenen” Bildern und inkompatiblen Formaten vermeidet.
Aus dem Entwurf kann sofort Folgendes erstellt werden:
- Online-Version
- Strikte und schöne PDF-Datei im gleichen Stil wie die Online-Version.
Aktuelle Dokumentationspraxis
Heute wird die Dokumentation:
- In Markdown geschrieben
- In GitLab gespeichert:
- für alle Mitarbeiter gemäß Rollenmodell zugänglich
- unterstützt mehrbenutzerfreundliche Bearbeitung
- Automatisch in eine Online-Version konvertiert:
- Es wird ein Docsify-Container verwendet
- Die Aktualisierung erfolgt jede Minute
- Websites werden über DNS (mit einem 3- oder 4-Level-Namen für jedes Projekt) im Internet veröffentlicht
- In PDF exportiert mit einer einheitlichen Vue.js-Formatierung, die für Website und Datei gleich ist
- Diagramme werden in zwei Formaten erstellt:
- Draw.io (outline, für komplexe Diagramme)
- Mermaid (inline, direkt in Markdown)
- Diagrammexport:
- in SVG (Hauptformat)
- manchmal in PNG (für inkompatible Plattformen)
- mit Einbindung des Quellcodes des Diagramms in die Datei.
Das Drei-Ebenen-Dokumentationsmodell – und seine Vereinfachung
Ursprünglich betrachtete ich drei Ebenen der Dokumentation:
- Entwürfe – persönliche, schnell wechselnde Notizen
- Häufig geänderte Dokumentation – gemeinsame Arbeitsmaterialien
- Statische Dokumentation – endgültige, geprüfte Versionen
Ich habe jedoch beschlossen:
- die Anonymität und Isolation von Entwürfen aufzugeben,
- die erste und zweite Ebene zu einer gemeinsamen Wiki-Entwurfsebene auf der Grundlage von Discourse zusammenzulegen
- die statische Dokumentation in GitLab + Docsify beizubehalten.
Obwohl es keine automatische Synchronisierung zwischen der zweiten und dritten Ebene gibt, halte ich diesen Ansatz für tragfähig: Er vereinfacht den Wissensfluss, senkt die Einstiegshürde für Kollegen und beschleunigt den Übergang von einer Idee zur Veröffentlichung.
Tools und Formate
||||
| — | — | — |
|Text|Markdown (.md)|Hauptformat zum Schreiben|
|Speicherung|GitLab|Versionskontrolle, Überprüfung, Zugriff nach Rollen|
|Online-Veröffentlichung|Docsify (in Docker-Container)|Automatische Websitegenerierung aus Git|
|Entwürfe und Diskussionen|Discourse|Gemeinsame Ausarbeitung von Ideen|
|Integrierte Diagramme|Mermaid|Blockdiagramme, Sequenzen direkt in Markdown|
|Externe Diagramme|Draw.io (.drawio → .svg)|Komplexe Architekturdiagramme|
|Export nach PDF|Docsify + einheitlicher Vue-Stil|Für Offline-Zugriff und Übermittlung an Kunden|\
Was noch fehlt
Es gibt noch Bereiche, in denen das System verbessert werden kann:
- Synchronisierung zwischen Discourse und GitLab
- Verfeinerung des Überprüfungsprozesses und Übergang in einen veröffentlichungsreifen Zustand der endgültigen Version
- Wahrung der referenziellen Integrität
- Automatisierung von Veröffentlichungen
- Mechanismus für Feedback zu gefundenen Inkonsistenzen und Benachrichtigungen über Korrekturen.