tech docs

Gov.uk One Login Technical Documentation

Este repositório contém documentação para ajudar os tecnólogos dos departamentos governamentais a bordo do Gov.uk One Login. É publicado usando o modelo de documentação técnica.

Fazendo alterações no conteúdo

A equipe de redação técnica do Gov.uk One Login possui essa documentação e é responsável por aprovar alterações de conteúdo. Está escrito para ser centrado no usuário e atender aos padrões de conteúdo GDS, o que significa seguir:

• GOV.UK Orientação sobre planejamento, escrita e gerenciamento de conteúdo
• o guia do estilo Gov.uk
• O Guia de Estilo Técnico Gov.uk
• Outros princípios de escrita claros

Se você trabalha no Gov.uk One Login, entre em contato com a equipe de redação de tecnologia para obter ajuda com alterações de conteúdo, a menos que seja pequeno e não afete o comportamento do usuário.

Pequenas mudanças de conteúdo incluem:

• Adicionando esclarecimentos para melhorar a compreensão
• corrigindo amostras de código
• Corrigindo links quebrados ou erros de digitação

Você pode fazer essas alterações e, em seguida, solicitar uma revisão de um escritor de tecnologia sobre a solicitação de tração. Se você não tiver certeza se uma alteração é pequena, entre em contato conosco em nosso canal de escritos de redação di-técnica.

Fazendo mudanças técnicas

A equipe de orquestração é responsável pela manutenção e saúde operacional da plataforma Docs Tech. Você deve consultá -los para aprovação de quaisquer alterações nesse espaço.

Exemplos incluem:

• Alterações nos fluxos de trabalho de ação do GitHub
• Alterações na implantação da AWS ou na infraestrutura
• Atualizações de dependência
• Atualizações Ruby que não alteram o conteúdo

Visualize suas mudanças de documentação

Para visualizar quaisquer alterações e adições que você fez na documentação em um navegador, clone este repositório e use o Dockerfile neste repositório para executar um servidor intermediário em sua máquina sem precisar configurar o Ruby localmente.

Essa configuração tem recarregamento ao vivo ativado, o que significa que suas alterações serão aplicadas ao editar arquivos no diretório de origem. A única exceção a isso é que, se você fizer alterações no config/tech-docs.yml , deverá parar e reiniciar o servidor para ver suas alterações na visualização. Você pode interromper o servidor com Ctrl-C .

Execute o script auxiliar:

./preview-with-docker.sh

Pode levar alguns minutos para construir o contêiner do Docker, principalmente se for a primeira vez que executa o script. Quando o servidor terminar de carregar, você deve ver a seguinte saída no 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.

Fazendo alterações em um diagrama

Os diagramas são contentes; portanto, depois de fazer uma alteração, você deve solicitar uma revisão da equipe de redação técnica.

Você pode editar os arquivos desenhados.io na pasta source/images/originals , instalando e usando o aplicativo Draw.io Desktop.

Use um arquivo de draw.io por diagrama.

Instalando o aplicativo Draw.io Desktop

Execute os seguintes comandos para usar o aplicativo Draw.io Desktop na linha de comando.

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

Editando e publicando um diagrama

Siga estas etapas:

1. Crie e modifique um diagrama usando draw.io.
2. Salve o arquivo draw.io na pasta source/images/originals .
3. Publique o diagrama como um gráfico vetorial escalável (SVG).
4. Salve o arquivo SVG na pasta source/images .

Comandos úteis

Atualize um diagrama:

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

Gere versões SVG dos diagramas e salve -os na pasta 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

Linhando o Gov.uk One Login Technical Documentation

Este repositório usa o Vale e o GDS Tech Docs Linter RegisSet.

Instalando o linhador em sua máquina local

Você precisa:

• Instale o homebrew
• Instale o Vale

Linering com seu editor de código

Muitos editores de código fornecem extensões ou plugins para a Vale, que podem levantar erros à medida que você atualiza a documentação. Você ainda precisará de Vale instalado em sua máquina local.

LING COM INTERFADA DE LINHA DE COMANDO VALE (CLI)

Por padrão, o Vale deve ser executado no mesmo diretório que este arquivo de configuração, a menos que o sinalizador --config forneça um caminho. Para executar o linhador usando a Vale CLI:

1. Em uma janela do terminal, navegue para o seu repositório.
2. Execute vale sync para baixar o pacote mais recente do Tech-Docs-Linter e descompactar isso no seu StylesPath listado no seu arquivo de configuração.
3. Execute o vale . Para fitar todo o repositório ou fornecer um caminho para um diretório apenas para fascar esse diretório, por exemplo: vale ./source/go-live

Atualizando para o último conjunto de regras do Tech Docs Docs Linter

Se uma nova regra for adicionada ao conjunto de regras do Tech Docs Linter, você poderá aumentar o pacote usado por este repositório quando estiver pronto. Uma versão posterior do conjunto de regras pode ser testada e adicionada por:

1. Crie uma filial.
2. Atualize o número da versão do pacote no arquivo de configuração Vale.
3. Execute vale sync para baixar e descompactar o pacote mais recente.
4. Execute vale ./source para testar o linhador.
5. Corrigir qualquer alteração Novo conjunto de regras aumenta (de preferência uma confirmação para cada violação de regra).
6. Aumente um PR com o número mais recente da versão no arquivo de configuração Vale.

Código de Conduta

Consulte o Código de Conduta alphagov .

Licença

Salvo indicação em contrário, a base de código é liberada sob a licença do MIT. Isso abrange a base de código e qualquer código de amostra na documentação.

A documentação é © Crown Copyright e disponível nos termos da licença Open Government 3.0.