tech docs

Gov.uk One Login Documentation technique

Ce repo contient une documentation pour aider les technologues des services gouvernementaux à bord de la connexion de Gov.uk One. Il est publié à l'aide du modèle de documentation technique.

Faire des modifications de contenu

L'équipe de rédaction technique Gov.uk One Login possède cette documentation et a la responsabilité d'approuver les changements de contenu. Il est écrit pour être centré sur l'utilisateur et respecter les normes de contenu GDS, ce qui signifie suivre:

• GOV.UK Guide sur la planification, l'écriture et la gestion du contenu
• Le guide de style Gov.uk
• Le guide de style technique Gov.uk
• Autres principes d'écriture clairs

Si vous travaillez sur Gov.uk One Connexion, vous devez contacter l'équipe d'écriture technologique pour obtenir de l'aide avec les modifications de contenu, sauf si elle est petite et n'affecte pas le comportement des utilisateurs.

Les petits changements de contenu incluent:

• ajouter des clarifications pour améliorer la compréhension
• Correction d'échantillons de code
• Fixation des liens cassés ou des fautes de frappe

Vous pouvez effectuer ces modifications vous-même, puis demander une revue de rédacteur technologique sur la demande de traction. Si vous ne savez pas si un changement est petit, contactez-nous sur notre canal Slack à écriture di-technique.

Apporter des changements techniques

L'équipe d'orchestration est responsable de la maintenance et de la santé opérationnelle de la plateforme Tech Docs. Vous devez les consulter pour l'approbation de tout changement dans cet espace.

Les exemples incluent:

• Modifications des flux de travail d'action GitHub
• Modifications apportées au déploiement AWS ou à la construction d'infrastructures
• Mises à jour de la dépendance
• Les mises à jour Ruby qui ne modifient pas le contenu

Aperçu de vos modifications de documentation

Pour prévisualiser toutes les modifications et ajouts que vous avez apportés à la documentation dans un navigateur, clonez ce référentiel et utilisez le dockerfile dans ce référentiel pour exécuter un serveur Middleman sur votre machine sans avoir à configurer Ruby localement.

Cette configuration a un rechargement en direct activé, ce qui signifie que vos modifications seront appliquées lorsque vous modifiez les fichiers dans le répertoire source. La seule exception à cela est que si vous apportez des modifications à config/tech-docs.yml , vous devez arrêter et redémarrer le serveur pour voir vos modifications dans l'aperçu. Vous pouvez arrêter le serveur avec Ctrl-C .

Exécutez le script d'assistance:

./preview-with-docker.sh

Il peut prendre quelques minutes pour construire le conteneur Docker, en particulier s'il s'agit de l'exécution du script. Lorsque le serveur a terminé le chargement, vous devez alors voir la sortie suivante dans le terminal:

== 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.

Apporter des modifications à un diagramme

Les diagrammes sont contenus, donc une fois que vous avez apporté un changement, vous devez demander un examen de l'équipe de rédaction technique.

Vous pouvez modifier les fichiers Draw.io dans le dossier source/images/originals en installant et en utilisant l'application de bureau Draw.io.

Utilisez un fichier Draw.io par diagramme.

Installation de l'application de bureau Draw.io

Exécutez les commandes suivantes pour utiliser l'application Draw.io Desktop à partir de la ligne de commande.

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

Édition et publication d'un diagramme

Suivez ces étapes:

1. Créer et modifier un diagramme à l'aide de Draw.io.
2. Enregistrez le fichier Draw.io dans le dossier source/images/originals .
3. Publiez le diagramme en tant que graphique vectoriel évolutif (SVG).
4. Enregistrez le fichier SVG dans le dossier source/images .

Commandes utiles

Mettre à jour un diagramme:

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

Générez des versions SVG des diagrammes et enregistrez-les dans le dossier 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

Liant la documentation technique de connexion Gov.uk One

Ce référentiel utilise Vale et le GDS Tech Docs Linter Ruleset.

Installation du linter sur votre machine locale

Vous devez:

• Installer Homebrew
• Installer Vale

Se liant à votre éditeur de code

De nombreux éditeurs de code fournissent des extensions ou des plugins pour Vale qui peuvent augmenter les erreurs lorsque vous mettez à jour la documentation. Vous aurez toujours besoin de Vale installée sur votre machine locale.

Liant avec l'interface de ligne de commande Vale (CLI)

Par défaut, Vale doit être exécuté à partir du même répertoire que ce fichier de configuration, à moins que l'indicateur --config ne soit fourni avec un chemin. Pour exécuter le linter à l'aide de Vale CLI:

1. Dans une fenêtre de terminal, accédez à votre dépôt.
2. Exécutez vale sync pour télécharger le dernier package Tech-Docs-Linter et décompressez-le sur votre StylesPath répertorié dans votre fichier de configuration.
3. Exécutez la commande vale . Pour Liter l'intégralité du dépôt ou fournir un chemin vers un répertoire à Lint uniquement ce répertoire par exemple: vale ./source/go-live

Mise à jour des derniers documents techniques Linter Ruleset

Si une nouvelle règle est ajoutée à l'éventail de règles de Docs Tech Docs, vous pouvez augmenter le package utilisé par ce référentiel lorsque vous êtes prêt. Une version ultérieure de l'ensemble de règles peut être testée et ajoutée par:

1. Créer une branche.
2. Mettez à jour le numéro de version du package dans le fichier Vale Config.
3. Exécutez vale sync pour télécharger et dézip le dernier package.
4. Exécutez vale ./source pour tester le linter.
5. Corrigez toutes les modifications que les nouveaux règles se présentent (de préférence un engagement pour chaque violation de la règle).
6. Soulevez un PR avec le dernier numéro de version dans le fichier Vale Config.

Code de conduite

Veuillez vous référer au code de conduite alphagov .

Licence

Sauf indication contraire, la base de code est libérée sous la licence MIT. Cela couvre à la fois la base de code et tout exemple de code dans la documentation.

La documentation est © Crown Copyright et disponible en vertu des termes de la licence Open Government 3.0.