Compartir a través de

Aportación de mejoras de calidad

No tiene que ser un experto en la materia ni un experto en documentación para contribuir. Si ve una oportunidad para mejorar la documentación, envíe una solicitud de incorporación de cambios con la mejora propuesta. En esta guía se describen varias formas sencillas de contribuir con mejoras de calidad en la documentación.

Nos centramos en estas áreas de calidad:

Aplicar formato a ejemplos de código

Todos los ejemplos de código deben seguir las directrices de estilo para el contenido de PowerShell. Estas reglas se repiten en forma abreviada aquí para mayor comodidad:

  • Todos los bloques de código deben estar contenidos en una valla de código de triple retroceso (```).
  • La longitud de línea para los bloques de código se limita a 90 caracteres en los artículos de referencia de cmdlet.
  • La longitud de línea de los bloques de código está limitada a 76 caracteres en los artículos about_*.
  • Evite usar caracteres de continuación de línea (`) en ejemplos de código de PowerShell.
    • Use oportunidades de salto de línea natural o de expansión, como después de los caracteres de canalización (|), las llaves de apertura (}), los paréntesis (() y los corchetes ([) para limitar la longitud de línea.
  • Incluya solo el símbolo del sistema de PowerShell para ejemplos ilustrativos donde el código no está destinado a copiar y pegar.
  • No utilice alias en los ejemplos a menos que esté documentando específicamente el alias.
  • Evite usar parámetros posicionales. Use el nombre del parámetro, incluso si el parámetro es posicional.

Sintaxis de comandos de formato

Todos los prose deben seguir las directrices de estilo para el contenido de PowerShell. Estas reglas se repiten aquí para mayor comodidad:

  • Use siempre el nombre completo de los cmdlets y parámetros. Evite usar alias a menos que se muestre específicamente el alias.
  • La propiedad, el parámetro, el objeto, los nombres de tipo, los nombres de clase, los métodos de clase deben estar en negrita.
    • Los valores de propiedad y parámetro deben encapsularse entre acentos graves (`).
    • Al hacer referencia a los tipos que usan el estilo entre corchetes, utilice acentos graves. Por ejemplo: [System.Io.FileInfo]
  • Los nombres de módulo de PowerShell deben estar en negrita.
  • Las palabras clave y los operadores de PowerShell deben estar en minúsculas.
  • Uso de mayúsculas y minúsculas (Pascal) adecuadas para los nombres y parámetros de los cmdlets.
  • Cuando se hace referencia a un parámetro por nombre, el nombre debe ser negrita.
  • Use el nombre del parámetro con el guion si está ilustrando la sintaxis. Envuelva el parámetro en comillas invertidas.
  • Cuando muestre el uso de ejemplo de un comando externo, el ejemplo deberá estar entre acentos graves. Incluya siempre la extensión de archivo del comando externo.

Para mejorar la mantenibilidad y legibilidad del código fuente en Markdown de nuestra documentación, estamos transformando nuestra documentación conceptual a usar referencias de vínculo en lugar de vínculos insertados.

Por ejemplo, en lugar de:

The [Packages tab](https://www.powershellgallery.com/packages) displays all available
packages in the PowerShell Gallery.

Debe ser:

The [Packages tab][01] displays all available packages in the PowerShell Gallery.

Nota:

Al reemplazar un enlace en línea, redistribuya el contenido para ajustarlo a 100 caracteres. Puede usar la extensión de el VS Code reflow-markdown para volver a dar formato rápidamente al párrafo.

En la parte inferior del archivo, agregue un comentario markdown antes de la definición de los vínculos.

<!-- Link references -->
[01]: https://www.powershellgallery.com/packages

Compruebe los siguiente:

  1. Cada vínculo apunta a la ubicación correcta.
  2. No duplique las definiciones de referencia de vínculo. Si ya existe una definición de referencia de vínculo para una dirección URL, reutilice la referencia existente en lugar de crear una nueva.
  3. Las definiciones de referencia de vínculo se encuentran en la parte inferior del archivo después del comentario markdown y están en el orden numérico.

Análisis de Markdown

Para cualquier artículo de uno de los repositorios participantes, al abrir el artículo en VS Code se muestran advertencias de linting. Solucione cualquiera de estas advertencias que encuentre, excepto:

  • MD022/blanks-around-headings/blanks-around-headers para el encabezado Synopsis en los documentos de referencia del cmdlet. Para esos elementos, la infracción de la regla es intencionada para asegurarse de que la documentación se compila correctamente con PlatyPS.

Asegúrese de las longitudes de línea y use la extensión Reflow Markdown para corregir las líneas largas.

Ortografía

A pesar de nuestros mejores esfuerzos, los errores tipográficos y los errores ortográficos pasan y terminan en la documentación. Estos errores hacen que la documentación sea más difícil de seguir y localizar. Corregir estos errores hace que la documentación sea más legible, especialmente para los hablantes que no son inglés que dependen de traducciones precisas.

  • Last updated on