tech docs

Gov.uk One Iniciar documentación técnica

Este repositorio contiene documentación para ayudar a los tecnólogos en los departamentos gubernamentales a bordo de Gov.uk One Inicie. Se publica utilizando la plantilla de documentación técnica.

Hacer cambios de contenido

El equipo de escritura técnica de inicio de sesión de Gov.uk One posee esta documentación y tiene la responsabilidad de aprobar los cambios de contenido. Está escrito para estar centrado en el usuario y cumplir con los estándares de contenido GDS, lo que significa seguir:

• Guía de Gov.uk sobre planificación, escritura y gestión de contenido
• la guía de estilo gov.uk
• la guía de estilo técnico de Gov.uk
• Otros principios de escritura claros

Si trabaja en el inicio de sesión de Gov.uk One, debe comunicarse con el equipo de redacción de tecnología para obtener ayuda con los cambios de contenido a menos que sea pequeño y no afecte el comportamiento del usuario.

Los pequeños cambios de contenido incluyen:

• Agregar aclaraciones para mejorar la comprensión
• corrección de muestras de código
• Arreglar enlaces rotos o errores tipográficos

Puede hacer estos cambios usted mismo y luego solicitar una revisión de un escritor técnico sobre la solicitud de extracción. Si no está seguro de si un cambio es pequeño, contáctenos en nuestro canal Slack #di-técnico de escritura.

Hacer cambios técnicos

El equipo de orquestación es responsable del mantenimiento y la salud operativa de la plataforma Tech Docs. Debe consultarlos para su aprobación de cualquier cambio en ese espacio.

Los ejemplos incluyen:

• Cambios a los flujos de trabajo de acción de Github
• Cambios en la implementación de AWS o construir infraestructura
• Actualizaciones de dependencia
• Actualizaciones de Ruby que no cambian el contenido

Vista previa de sus cambios de documentación

Para obtener una vista previa de cualquier cambio y adición que haya realizado en la documentación en un navegador, clone este repositorio y use el DockerFile en este repositorio para ejecutar un servidor Middleman en su máquina sin tener que configurar Ruby localmente.

Esta configuración tiene habilitado Live Reload, lo que significa que sus cambios se aplicarán a medida que edite archivos en el directorio de origen. La única excepción a esto es si realiza cambios en config/tech-docs.yml , debe detener y reiniciar el servidor para ver sus cambios en la vista previa. Puede detener el servidor con Ctrl-C .

Ejecute el guión de ayuda:

./preview-with-docker.sh

Puede tomar unos minutos construir el contenedor Docker, particularmente si es la primera vez que ejecuta el script. Cuando el servidor ha terminado de cargar, debe ver la siguiente salida en el 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.

Haciendo cambios en un diagrama

Los diagramas están contentos, por lo que una vez que haya realizado un cambio, debe solicitar una revisión del equipo de redacción técnica.

Puede editar los archivos Draw.io en la carpeta source/images/originals al instalar y usar la aplicación Draw.io Desktop.

Use un archivo Draw.io por diagrama.

Instalación de la aplicación Draw.io Desktop

Ejecute los siguientes comandos para usar la aplicación Draw.io Desktop desde la línea de comandos.

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

Edición y publicación de un diagrama

Sigue estos pasos:

1. Cree y modifique un diagrama usando Draw.io.
2. Guarde el archivo Draw.io en la carpeta source/images/originals .
3. Publique el diagrama como un gráfico vectorial escalable (SVG).
4. Guarde el archivo SVG en la carpeta source/images .

Comandos útiles

Actualizar un diagrama:

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

Genere versiones SVG de los diagramas y guárdelos en la carpeta 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

Limpio de la documentación técnica de inicio de sesión de Gov.uk One

Este repositorio utiliza Vale y el conjunto de reglas de los deladores GDS Tech Docs.

Instalación del enlace en su máquina local

Necesitas:

• Instalar Homebrew
• instalar valle

Tontar con su editor de códigos

Muchos editores de código proporcionan extensiones o complementos para Vale, lo que puede aumentar los errores a medida que actualiza la documentación. Todavía necesitará que Vale instale en su máquina local.

Tontar con la interfaz de línea de comandos de Vale (CLI)

De forma predeterminada, Vale debe ejecutarse desde el mismo directorio que este archivo de configuración, a menos que el indicador --config sea proporcionado con una ruta. Para ejecutar el enlace usando Vale CLI:

1. En una ventana de terminal, navegue a su repositorio.
2. Ejecute vale sync para descargar el último paquete Tech-Docs-Linter y descifrarlo a su StylesPath en su archivo de configuración.
3. Ejecute el vale . para pelear todo el repositorio o proporcionar una ruta a un directorio a la pelusa solo de ese directorio, por ejemplo: vale ./source/go-live

Actualización del último conjunto de reglas de Tech Docs Docs

Si se agrega una nueva regla al conjunto de reglas de Live Docs Tech, puede aumentar el paquete utilizado por este repositorio cuando esté listo. Una versión posterior del conjunto de reglas puede ser probada y agregada por:

1. Crear una rama.
2. Actualice el número de versión del paquete en el archivo de configuración de Vale.
3. Ejecute vale sync para descargar y descomponer el último paquete.
4. Ejecute vale ./source para probar el enlace.
5. Arregle cualquier cambio de nueva Reglas El conjunto de conjuntos (preferiblemente una confirmación para cada violación de la regla).
6. Aproveche un PR con el último número de versión en el archivo de configuración de Vale.

Código de conducta

Consulte el Código de Conducta de alphagov .

Licencia

A menos que se indique lo contrario, la base de código se publica bajo la licencia MIT. Esto cubre tanto la base de código como cualquier código de muestra en la documentación.

La documentación es © Crown Copyright y está disponible bajo los términos de la licencia Open Government 3.0.