Compartir a través de

Lista de comprobación del editor

Este artículo contiene una lista resumida de reglas para escribir o editar documentación de PowerShell. Consulte otros artículos de la Guía del colaborador para obtener explicaciones detalladas y ejemplos de estas reglas.

Metadatos

  • ms.date: debe tener el formato MM/DD/AAAA
    • Cambiar la fecha en que hay una actualización significativa o fáctica
      • Reorganización del artículo
      • Corrección de errores fácticos
      • Agregar nueva información
    • No cambie la fecha si la actualización es insignificante
      • Corrección de errores tipográficos y formato
  • title: cadena única de 43-59 caracteres de longitud (incluidos los espacios)
    • No incluya el identificador de sitio (se genera automáticamente).
    • Uso de mayúsculas en las frases: capitalice solo la primera palabra y los nombres propios.
  • description: 115-145 caracteres, incluidos los espacios: este resumen se muestra en el resultado de la búsqueda.

Formato

  • Elementos de sintaxis inversa que aparecen, insertados, dentro de un párrafo
    • Nombres de cmdlet Verb-Noun
    • Variable $counter
    • Ejemplos sintácticos Verb-Noun -Parameter
    • Rutas de archivo C:\Program Files\PowerShell, /usr/bin/pwsh
    • Direcciones URL que no están diseñadas para que se puedan hacer clic en el documento
    • Valores de propiedad o parámetro
  • Use negrita para los nombres de propiedad, los nombres de parámetro, los nombres de clase, los nombres de módulo, los nombres de entidad, el objeto o los nombres de tipo.
    • Negrita se usa para el marcado semántico, sin énfasis
    • Negrita: usar asteriscos **
  • Cursiva: usar subrayado _
    • Solo se usa para el énfasis, no para el marcado semántico
  • Saltos de línea en 100 columnas (o en 80 para about_Topics)
  • Sin pestañas duras: utilice solo espacios
  • No deben quedar espacios al final de las líneas
  • 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

encabezados

  • Comience primero con H1: solo un H1 por artículo
  • Usa solo encabezados ATX
  • Usa minúsculas iniciales en todos los encabezados
  • No omitir niveles: ningún H3 sin un H2
  • Limitar la profundidad del encabezado a H3 o H4
  • Agregar líneas en blanco antes y después
  • No agregar ni quitar encabezados: PlatyPS aplica encabezados específicos en su esquema

Bloques de código

  • Agregar líneas en blanco antes y después
  • Uso de barreras de código etiquetadas: powershell, Salida u otro identificador de idioma adecuado
  • Utiliza una cerca de código sin etiquetar para los bloques de sintaxis
  • Coloque la salida en un bloque de código independiente, excepto en los ejemplos básicos en los que no pretende que el lector use el botón Copiar .
  • Consulte la lista de idiomas admitidos.

Listas

  • Sangría correctamente
  • Agregar líneas en blanco antes del primer elemento y después del último elemento
  • Utiliza guion (-) para viñetas en lugar de asterisco (*) para reducir la confusión con el énfasis.
  • Usar 1. para todos los elementos de una lista numerada

Terminología

Ejemplos de referencia de cmdlets

  • Debe tener al menos un ejemplo en la referencia de cmdlet.

  • Los ejemplos solo deben ser código suficiente para demostrar el uso

  • Sintaxis de PowerShell

    • Uso de nombres completos de cmdlets y parámetros: sin alias
    • Utilice el despliegue para parámetros cuando la línea de comandos se haga demasiado larga.
    • Evitar el uso de comillas inversas para la continuación de línea; úselas solo cuando sea necesario.

  • Quite o simplifique el prompt de PowerShell (PS>), excepto cuando sea necesario para algún ejemplo.

  • El ejemplo de referencia de Cmdlet debe seguir el siguiente esquema PlatyPS.

    ### Example 1 - Descriptive title

Zero or more short descriptive paragraphs explaining the context of the example followed by one or
more code blocks. Recommend at least one and no more than two.

```powershell
... one or more PowerShell code statements ...
```

```Output
Example output of the code above.
```

Zero or more optional follow up paragraphs that explain the details of the code and output.

  • no coloque párrafos entre los bloques de código. Todo el contenido descriptivo debe aparecer antes o después de los bloques de código.

Vinculación a otros documentos

  • Al vincular fuera del conjunto de documentos o entre referencia de cmdlet y conceptual
    • Usar direcciones URL relativas al sitio al vincular a Microsoft Learn (quitar https://learn.microsoft.com/en-us)
    • no incluya la localización en las direcciones URL de las propiedades de Microsoft (quitar /en-us de la URL)
    • Todas las direcciones URL a sitios web externos deben usar HTTPS a menos que no sea válido para el sitio de destino.
  • Al vincular dentro del conjunto de documentos
    • Usar la ruta de acceso de archivo relativa (../folder/file.md)
  • Todas las rutas de acceso usan caracteres de barra diagonal (/)
  • Los vínculos de imagen deben tener texto alternativo único