tech docs

GOV.UK One Login Technische Dokumentation

Dieses Repo enthält eine Dokumentation, mit der Technologen in Regierungsabteilungen an Bord von Gov.uk One Login helfen können. Es wird mit der technischen Dokumentationsvorlage veröffentlicht.

Inhalte Änderungen vornehmen

Das Team Gov.uk One Login Technical Writing besitzt diese Dokumentation und übernimmt die Verantwortung für die Genehmigung von Inhalten Änderungen. Es wird so geschrieben, dass es benutzerorientiert ist und GDS-Inhaltsstandards erfüllt, was bedeutet, dass sie folgt:

• GOV.UK -Anleitung zum Planen, Schreiben und Verwalten von Inhalten
• Der Gov.uk -Style Guide
• Der Gov.uk Technical Style Guide
• Andere klare Schreibprinzipien

Wenn Sie an Gov.uk One Login arbeiten, sollten Sie sich an das Tech -Schreibteam wenden, um Hilfe bei Inhaltsänderungen zu erhalten, es sei denn, es ist klein und wirkt sich nicht auf das Benutzerverhalten aus.

Kleine Änderungen in den Inhalten umfassen:

• Ergänzung von Klarstellungen zur Verbesserung des Verständnisses
• Korrekturcode -Beispiele
• Beheben von defekten Links oder Tippfehler

Sie können diese Änderungen selbst vornehmen und dann eine Tech -Autor -Bewertung auf der Pull -Anfrage anfordern. Wenn Sie sich nicht sicher sind, ob eine Änderung klein ist, kontaktieren Sie uns auf unserem #technischen Slack-Kanal.

Technische Änderungen vornehmen

Das Orchestrierungsteam ist für die Wartung und die betriebliche Gesundheit der Tech -Dokument -Plattform verantwortlich. Sie sollten sie zur Genehmigung von Änderungen in diesem Bereich konsultieren.

Beispiele sind:

• Änderungen der GitHub -Aktions -Workflows
• Änderungen an der AWS -Bereitstellung oder der Erstellung der Infrastruktur
• Abhängigkeitsaktualisierungen
• Ruby -Updates, die den Inhalt nicht ändern

Vorschau Ihrer Dokumentationsänderungen

Um Änderungen und Ergänzungen voranzutreiben, die Sie in der Dokumentation in einem Browser vorgenommen haben, klonen Sie dieses Repo und verwenden Sie die Docker -Datei in diesem Repo, um einen Mittelsmesserserver auf Ihrem Computer auszuführen, ohne Ruby lokal einrichten zu müssen.

Dieses Setup ist Live Reload aktiviert, was bedeutet, dass Ihre Änderungen angewendet werden, wenn Sie Dateien im Quellverzeichnis bearbeiten. Die einzige Ausnahme ist, wenn Sie Änderungen an config/tech-docs.yml vornehmen. Sie müssen den Server anhalten und neu starten, um Ihre Änderungen in der Vorschau anzuzeigen. Sie können den Server mit Ctrl-C stoppen.

Führen Sie das Helfer -Skript aus:

./preview-with-docker.sh

Der Bau des Docker -Containers kann einige Minuten dauern, insbesondere wenn Sie zum ersten Mal das Skript ausführen. Wenn der Server das Laden beendet hat, sollten Sie die folgende Ausgabe im Terminal sehen:

== View your site at " http://localhost:4567 " , " http://127.0.0.1:4567 "
== Inspect your site configuration at " http://localhost:4567/__middleman " , " http://127.0.0.1:4567/__middleman " /usr/local/bundle/gems/tilt-2.0.11/lib/tilt/redcarpet.

Änderungen an einem Diagramm vornehmen

Diagramme sind zufrieden. Sobald Sie eine Änderung vorgenommen haben, sollten Sie eine Überprüfung vom technischen Schreibteam anfordern.

Sie können die Dateien draw.io im Ordner " source/images/originals bearbeiten, indem Sie die Desktop -App zeichnen und verwenden.

Verwenden Sie eine Datei draw.io pro Diagramm.

Installieren Sie die Desktop -App von Draw.io

Führen Sie die folgenden Befehle aus, um die Desktop -App von Draw.io aus der Befehlszeile zu verwenden.

 brew install --cask drawio
alias draw.io='/Applications/draw.io.app/Contents/MacOS/draw.io'

Bearbeitung und Veröffentlichung eines Diagramms

Folgen Sie folgenden Schritten:

1. Erstellen und ändern Sie ein Diagramm mit Draw.io.
2. Speichern Sie die Datei dract.io in den Ordner source/images/originals .
3. Veröffentlichen Sie das Diagramm als skalierbare Vektorgrafik (SVG).
4. Speichern Sie die SVG -Datei in source/images -Ordner.

Nützliche Befehle

Aktualisieren Sie ein Diagramm:

 draw.io source/images/originals/top-level-technical-diagram.drawio

Generieren Sie SVG -Versionen der Diagramme und speichern Sie sie im Ordner source/images/originals :

 draw.io -x -o source/images/top-level-technical-diagram.svg source/images/originals/top-level-technical-diagram.drawio

draw.io -x -o source/images/technical-flow-diagram.svg source/images/originals/technical-flow-diagram.drawio

LINTING DER GOV.UK One Login Technische Dokumentation

Dieses Repository verwendet Vale und die GDS -Tech -Dokumente für den Linter Ruleset.

Installieren des Linters auf Ihrem lokalen Computer

Sie müssen:

• Homebrew installieren
• Vale installieren

Linie mit Ihrem Code -Editor

Viele Code -Redakteure bieten Erweiterungen oder Plugins für Vale, die bei der Aktualisierung der Dokumentation Fehler aufnehmen können. Sie müssen noch Vale auf Ihrem lokalen Computer installiert.

Linie mit Vale -Befehlszeilenschnittstelle (CLI)

Standardmäßig muss Vale aus demselben Verzeichnis wie diese Konfigurationsdatei ausgeführt werden, es sei denn, das Flag --config wird mit einem Pfad bereitgestellt. Um den Linter mit Vale CLI auszuführen:

1. Navigieren Sie in einem Terminalfenster zu Ihrem Repo.
2. Führen Sie vale sync aus, um das neueste Tech-DocS-L-L-L-L-Paket herunterzuladen, und entpacken Sie es in Ihren StylesPath der in Ihrer Konfigurationsdatei aufgeführt ist.
3. Führen Sie den Befehlsvale aus vale . Um das vale ./source/go-live Repo abzuspinn

Aktualisierung der neuesten Tech -Dokumente Linter Regelnsatz

Wenn die Tech -Dokumente ein neuer Regel hinzugefügt wird, können Sie das von diesem Repo verwendete Paket aufgreifen, wenn Sie bereit sind. Eine spätere Version des Regelnsatzes kann getestet und hinzugefügt werden von:

1. Erstellen Sie einen Zweig.
2. Aktualisieren Sie die Paketversionsnummer in der Vale -Konfigurationsdatei.
3. Führen Sie vale sync aus, um das neueste Paket herunterzuladen und zu öffnen.
4. Führen Sie vale ./source aus, um den Linter zu testen.
5. Beheben Sie alle Änderungen, die neue Regeln auswirken (vorzugsweise ein Commit für jede Regelverletzung).
6. Erhöhen Sie eine PR mit der neuesten Versionsnummer in der Vale -Konfigurationsdatei.

Verhaltenskodex

Weitere Informationen finden Sie im alphagov -Verhaltenskodex.

Lizenz

Sofern nicht anders angegeben, wird die Codebasis unter der MIT -Lizenz veröffentlicht. Dies deckt sowohl die Codebasis als auch jeden Beispielcode in der Dokumentation ab.

Die Dokumentation lautet © Crown Copyright und erhältlich unter den Bedingungen der Open Government 3.0 -Lizenz.