Comece a contribuir para a documentação do PowerShell

Este artigo é uma visão geral de como começar a trabalhar como colaborador da documentação do PowerShell.

Estrutura do PowerShell-Docs

Há três categorias de conteúdo no repositório PowerShell-Docs:

• conteúdo de referência
• conteúdo conceitual
• metadados e arquivos de configuração

Conteúdo de referência

O conteúdo de referência é a referência de cmdlet do PowerShell para os cmdlets fornecidos no PowerShell. A referência do cmdlet é coletada em pastas versionadas (como 5.1, 7.4, 7.5 e 7.6), que contêm a referência para os módulos fornecidos com o PowerShell. Esse conteúdo também é usado para criar as informações de ajuda exibidas pelo cmdlet Get-Help.

Conteúdo conceitual

A documentação conceitual não é organizada por versão. Todos os artigos são exibidos para todas as versões do PowerShell.

Nota

Sempre que um artigo conceitual é adicionado, removido ou renomeado, o TOC deve ser atualizado. Todos os arquivos excluídos ou renomeados devem ser redirecionados.

Arquivos de metadados

Este projeto contém vários tipos de arquivos de metadados. Os arquivos de metadados controlam o comportamento de nossas ferramentas de build e do sistema de publicação. Somente PowerShell-Docs mantenedores e colaboradores aprovados têm permissão para alterar esses arquivos. Se você achar que um arquivo meta deve ser alterado, abra um problema para discutir as alterações necessárias.

Arquivos de meta na raiz do repositório

• .* – arquivos de configuração na raiz do repositório
• *.md – Documentação do projeto na raiz do repositório
• *.yml – Documentação do projeto na raiz do repositório
• .devcontainer/* – arquivos de configuração do devcontainer
• .github/**/* – modelos, ações e outros metadados do GitHub
• .vscode/**/* – configurações de extensão do VS Code
• assets/* - contém arquivos para download vinculados na documentação
• redir/* – contêm arquivos de mapeamento de redirecionamento
• tests/* – ferramentas de teste usadas pelo sistema de build
• tools/* – outras ferramentas usadas pelo sistema de build

Meta-arquivos no conjunto de documentação

• reference/**/*.json – arquivos de configuração do docset
• reference/**/*.yml – TOC e outros arquivos de conteúdo estruturados
• reference/bread/* – configuração da navegação na trilha
• reference/includes/* – markdown de arquivos de inclusão
• reference/mapping/* – configuração de mapeamento de versão
• reference/**/media/** – arquivos de imagem usados na documentação
• reference/module/* – configuração da página do Navegador de Módulos

Criando novos artigos

Um issue do GitHub deve ser criado para qualquer novo documento ao qual você deseja contribuir. Verifique se há problemas existentes para verificar se você não está duplicando os esforços. Os problemas atribuídos são considerados como in progress. Se você quiser colaborar em um problema, entre em contato com a pessoa atribuída ao problema.

De modo parecido ao processo RFC do PowerShell, crie um problema antes de escrever o conteúdo. Essa questão garante que você não perca tempo e esforço em um trabalho que será rejeitado pela equipe de PowerShell-Docs. O problema nos permite consultar você sobre o escopo do conteúdo e onde ele se encaixa na documentação do PowerShell. Todos os artigos devem ser incluídos no Sumário (TOC). O local do TOC proposto deve ser incluído na discussão da questão.

Nota

O sistema de publicação gera automaticamente o TOC para conteúdo de referência. Você não precisa atualizar o TOC.

Atualizando artigos existentes

Quando aplicável, os artigos de referência do cmdlet são duplicados em todas as versões do PowerShell mantidas neste repositório. Ao relatar um problema sobre uma referência de cmdlet ou um artigo About_, liste as versões do artigo que têm o problema.

Aplique a alteração apropriada a cada versão do arquivo.

Conteúdo localizado

A documentação do PowerShell é escrita em inglês e traduzida para outros 17 idiomas. O conteúdo em inglês é armazenado no repositório GitHub chamado MicrosoftDocs/PowerShell-Docs. Problemas encontrados no conteúdo traduzido devem ser enviados para este repositório.

Todas as traduções começam primeiro do conteúdo em inglês. Usamos tradução humana e de máquina.

Método de tradução	Idiomas
Tradução humana	de-DE, es-ES, fr-FR, it-IT, ja-JP, ko-KR, pt-BR, ru-RU, zh-CN, zh-TW
Tradução automática	cs-CZ, hu-HU, nl-NL, pl-PL, pt-PT, sv-SE, tr-TR

O conteúdo traduzido pela tradução automática pode nem sempre resultar em escolhas de palavras e gramática corretas. Se você encontrar um erro na tradução para qualquer idioma, em vez de nos detalhes técnicos do artigo, abra um problema explicando por que você acha que a tradução está errada.

Alguns problemas de tradução podem ser corrigidos alterando os arquivos de origem em inglês. Entretanto, alguns problemas podem exigir atualizações em nosso sistema interno de tradução. Para esses casos, devemos enviar o problema à nossa equipe de localização interna para revisão e resposta.

Próximas etapas

Há duas maneiras comuns de enviar alterações no GitHub. Ambos os métodos são descritos no Guia central do Colaborador:

1. Você pode fazer edições rápidas em documentos existentes na interface da Web do GitHub.
2. Use o de fluxo de trabalho completo do GitHub para adicionar novos artigos, atualizar vários arquivos ou outras alterações grandes.

Antes de iniciar as alterações, você deve criar um fork do repositório PowerShell-Docs. As alterações devem ser feitas em um branch de trabalho em sua versão local do PowerShell-Docs. Se você estiver usando o método de edição rápida no GitHub, essas etapas serão automaticamente executadas para você. Se você estiver usando o fluxo de trabalho completo do GitHub , você deve estar configurado para trabalhar localmente.

Ambos os métodos terminam com a criação de uma PR (Pull Request). Para obter mais informações e práticas recomendadas, consulte Enviando uma solicitação de pull.