Introducción a la contribución a la documentación de PowerShell

Este artículo es una introducción a cómo empezar a trabajar como colaborador en la documentación de PowerShell.

Estructura de PowerShell-Docs

Hay tres categorías de contenido en el repositorio de PowerShell-Docs:

• contenido de referencia
• contenido conceptual
• metadatos y archivos de configuración

Contenido de referencia

El contenido de referencia es la referencia de cmdlets de PowerShell para los cmdlets enviados en PowerShell. La referencia del cmdlet se recopila en carpetas versionadas (como 5.1, 7.4, 7.5 y 7.6), que contienen la referencia de los módulos que se envían con PowerShell. Este contenido también se usa para crear la información de ayuda que muestra el cmdlet Get-Help.

Contenido conceptual

La documentación conceptual no está organizada por versión. Todos los artículos se muestran para cada versión de PowerShell.

Nota

Cada vez que se agrega, quita o cambia el nombre de un artículo conceptual, se debe actualizar el TOC. Los archivos eliminados o cambiados de nombre deben redirigirse.

Archivos de metadatos

Este proyecto contiene varios tipos de archivos de metadatos. Los archivos de metadatos controlan el comportamiento de nuestras herramientas de compilación y el sistema de publicación. Solo los mantenedores y colaboradores aprobados de PowerShell-Docs pueden cambiar estos archivos. Si cree que se debe cambiar un archivo meta, abra un problema para analizar los cambios necesarios.

Metadatos en la raíz del repositorio

• .*: archivos de configuración en la raíz del repositorio
• *.md: documentación del proyecto en la raíz del repositorio
• *.yml: documentación del proyecto en la raíz del repositorio
• .devcontainer/*: archivos de configuración de devcontainer
• .github/**/*: plantillas, acciones y otros metadatos de GitHub
• .vscode/**/*: configuraciones de extensión de VS Code
• assets/*: contiene archivos descargables vinculados en la documentación
• redir/* - contiene archivos de asignación de redirección
• tests/*: herramientas de prueba usadas por el sistema de compilación
• tools/*: otras herramientas que usa el sistema de compilación

Archivos de metadatos del conjunto de documentación

• reference/**/*.json - archivos de configuración del conjunto de documentación
• reference/**/*.yml: TOC y otros archivos de contenido estructurados
• reference/bread/*: configuración de ruta de navegación
• reference/includes/*: archivos de inclusión Markdown
• reference/mapping/*: configuración de asignación de versiones
• reference/**/media/**: archivos de imagen usados en la documentación
• reference/module/*: Configuración de la página del Explorador de módulos

Creación de nuevos artículos

Se debe crear un "issue" de GitHub para cualquier documento nuevo que desee contribuir. Compruebe si hay problemas existentes para asegurarse de que no está duplicando los esfuerzos. Los problemas asignados se consideran in progress. Si desea colaborar en un problema, póngase en contacto con la persona asignada al problema.

De forma similar al proceso de RFC de PowerShell , cree un problema antes de escribir el contenido. El problema le evita perder tiempo y esfuerzo en trabajos que el equipo de PowerShell-Docs rechaza. El asunto nos permite consultarle sobre el alcance del contenido y dónde encaja en la documentación de PowerShell. Todos los artículos deben incluirse en la Tabla de contenido (TOC). La ubicación propuesta de la TOC debe incluirse en la discusión del problema.

Nota

El sistema de publicación genera automáticamente la TOC para el contenido de referencia. No tiene que actualizar el TOC.

Actualización de artículos existentes

Si procede, los artículos de referencia de cmdlet se duplican en todas las versiones de PowerShell mantenidas en este repositorio. Al notificar un problema sobre una referencia de cmdlet o un artículo de About_, enumere las versiones del artículo que tienen el problema.

Aplique el cambio adecuado a cada versión del archivo.

Contenido localizado

La documentación de PowerShell se escribe en inglés y se traduce en 17 otros idiomas. El contenido en inglés se almacena en el repositorio de GitHub denominado MicrosoftDocs/PowerShell-Docs. Los problemas encontrados en el contenido traducido deben enviarse a este repositorio.

Todas las traducciones comienzan primero desde el contenido en inglés. Usamos la traducción humana y automática.

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

Es posible que el contenido traducido mediante traducción automática no siempre incluya la elección de palabras y la gramática correctas. Si encuentra un error en la traducción de cualquier idioma, en lugar de en los detalles técnicos del artículo, abra un problema que explique por qué cree que la traducción es incorrecta.

Algunos problemas de traducción se pueden corregir cambiando los archivos de origen en inglés. Sin embargo, algunas incidencias pueden requerir actualizaciones de nuestro sistema interno de traducción. Para esos casos, debemos enviar el problema al equipo de localización interno para revisar y responder.

Pasos siguientes

Hay dos formas comunes de enviar cambios en GitHub. Ambos métodos se describen en la Guía central del colaborador:

1. Puede hacer modificaciones rápidas en los documentos existentes en la interfaz web de GitHub.
2. Use el flujo de trabajo completo de GitHub para agregar nuevos artículos, actualizar varios archivos u otros cambios grandes.

Antes de realizar cualquier cambio, debe crear una bifurcación del repositorio de PowerShell-Docs. Los cambios se deben realizar en una rama de trabajo en la copia de PowerShell-Docs. Si usa el método de edición rápida en GitHub, estos pasos se gestionan automáticamente. Si usa el flujo de trabajo completo de GitHub, debe estar preparado para trabajar localmente.

Ambos métodos terminan con la creación de una solicitud de incorporación de cambios (PR). Para obtener más información y las mejores prácticas, consulte Envío de un pull request.