Wikinoticias:Documentación de plantilla

Las plantillas son una parte muy poderosa de MediaWiki, pero pueden ser confusas para nuevos usuarios, e incluso los más experimentados pueden tener dificultad con las más complejas. Las plantillas deberán, en consecuencia, estar acompañadas por una documentación para ayudar en el uso por parte del usuario promedio.

La documentación deberá explicar qué hace una plantilla y cómo usarla. Debe ser lo suficientemente simple para que un usuario sin conocimientos profundos sobre plantillas puedan utilizarlas correctamente. Esto es especialmente cierto en el caso de plantillas utilizadas ampliamente.

Qué incluir

La documentación deberá cubrir:

• El propósito básico de la plantilla: qué hace, y (si no es obvio) por qué lo hace. Si hay plantillas con propósitos similares, es una buena idea mencionarlas también y así reducir las probabilidades de que sea mal utilizada.
• Cualquier parámetro que la plantilla tenga. Hay que explicar si son numerados o nombrados, si son o no opcionales (si no lo son, cuál es el valor por default), y que efecto puede tener. Si un parámetro está limitado ("si" o "no", por ejemplo), tiene que ser un número, todo esto debe ser dado en claro.
• Ejemplos de uso. Se debe especificar el wikitexto exacto que deberá ser usado, y el resultado que produce, y debe ser fácil de copiar al utilizar <code>...</code> o un cuadro con <pre>...</pre>.
• Plantillas relacionadas Si la plantilla es una de una serie de plantillas, incluye los enlaces a estas – en particular, asegúrate de que cada plantilla de la serie esté enlazada con el resto, ya que hace la navegación más fácil.
• categorías e interwikis apropiados, donde sea aplicable. Las categorías de plantillas se encuentran en Categoría:Plantillas. Estos deberán incluirse en la página de documentación utilizando tags <includeonly></includeonly>

Subpágina

La documentación de plantilla se ubicará en una subpágina de la plantilla (/uso), que estará transcluida al final de la plantilla. Entonces, si se tiene Plantilla:X, la documentación estará en Plantilla:X/uso

Al final de la plantilla en sí se colocará la plantilla {{uso de plantilla}}, que como se puede ver si se abre el enlace anterior, produce un cuadro verde donde estará la documentación. La plantilla {{uso de plantilla}} estará alrededor de tags <noinclude>...</noinclude>, y al final de la última línea de la plantilla, para que no se muestre cuando la plantilla sea utilizada.

Convenciones

La plantilla {{uso de plantilla}} será añadida al final de la página, así:

[-- última línea de la plantilla --]<noinclude>
{{uso de plantilla}}
</noinclude>

Si no existe una página de documentación, entonces se deberá crearla. En el caso de que no exista aún la página de documentación pero la plantilla es añadida, se especificará que no existe tal página y se dará un enlace; si primero se añade la plantilla {{uso de plantilla}} y luego cliquea en el enlace que esta produce al no tener subpágina de documentación, se puede utilizar precarga para crear la página más fácil.

Asegúrate de que el código de <noinclude> comience luego del último carácter del código de la plantilla, y no en una nueva línea. De otro modo, el espacio extra se insertará debajo de la plantilla cuando se la utilice, lo que no es usualmente lo deseado.

Categorías e interwikis

Añade las categorías e interwikis (que sean utilizados en la plantilla en sí, pero no al ser transcluida) en la página de documentación, ya que así la documentación no deberá estar esparcida en dos páginas.

• Para categorizar la plantilla, añade la categoría entre tags <includeonly>...<includeonly> en la subpágina de documentación.
• Para añadir interwikis a la plantilla, añade los interwikis entre los mismos tags <includeonly>...<includeonly> que se habían utilizado en la subpágina de documentación.
• Para categorizar la subpágina, cuya categoría deberá ser únicamente [[Wikinoticias:Indicaciones para el uso de plantillas]], añade [[Categoría:Wikinoticias:Indicaciones para el uso de plantillas]] entre las etiquetas <noinclude>...</noinclude> o usa la plantilla {{subpágina de documentación}}, la cual se coloca automáticamente con la precarga.
• Para que la plantilla categorice un artículo, es decir, que al ser transcluida añada un artículo a alguna categoría, la categoría deberá estar entre tags <includeonly>...<includeonly> en la plantilla, no la subpágina.

Ventajas

• Se separa el código complicado de las plantillas del de documentación, haciéndolo más fácil de editar.
• Permite que las instrucciones de las plantillas protegidas puedan ser editada.
• Introducir la documentación en una subpágina hace que sea menor el texto que tiene que ser procesado cada vez que la plantilla es transcluida, razón por la cual los desarrolladores de MediaWiki lo han recomendado

Véase también

• {{uso de plantilla}} – La plantilla que deberá utilizarse para crear la subpágina de documentación de plantilla
• <noinclude> e <includeonly>