Las plantillas son una característica muy poderosa de MediaWiki , pero pueden resultar confusas para los nuevos usuarios e incluso los usuarios experimentados pueden tener dificultades para entender las más complejas. Por lo tanto, las plantillas deben ir acompañadas de documentación para mejorar su usabilidad.
La documentación de la plantilla debe explicar qué hace una plantilla y cómo usarla. Debería ser lo suficientemente simple como para que un usuario sin un conocimiento completo de las complejidades de la sintaxis de las plantillas (lo que incluye a muchos contribuyentes experimentados que centran su atención en otra parte) pueda usarlo correctamente. Esto es especialmente cierto en el caso de plantillas muy utilizadas.
Los editores deben ceder a las políticas o pautas oficiales cuando las páginas de documentación de plantilla no sean consistentes con los estándares y principios comunitarios establecidos. Los editores también deben evitar "citar" páginas de documentación de plantilla como si fueran políticas, incluida esta guía práctica . Las páginas de documentación de plantilla se pueden escribir sin mucho debate (si es que hay alguno), a diferencia de las políticas de Wikipedia que han sido examinadas minuciosamente por la comunidad (consulte WP: Consenso local para más detalles).
La documentación de la plantilla debe cubrir:
<code>...</code>contenedor, para que quede claro y easy to copy, like this. Si la plantilla se puede utilizar de varias maneras, con o sin parámetros opcionales, por ejemplo, proporcione una variedad de ejemplos. Una buena manera de hacerlo es incluir la plantilla en la documentación varias veces (es decir, usar ejemplos en vivo), con parámetros diferentes cada vez y enumerar los parámetros utilizados en cada caso. Con {{Xpd}} esto se puede hacer sin tener que colocar la llamada de plantilla dos veces en el wikitexto.<noinclude>...</noinclude>contenedor en una plantilla o dentro de<includeonly>{{Sandbox other||...}}</includeonly>etiquetas si se colocan en una página de documentación. Hay muchas categorías de plantillas disponibles; consulte: Categoría:Plantillas de Wikipedia para explorarlas.La Wikipedia en inglés es una fuente de plantillas para cientos de otras Wikipedias y proyectos hermanos. A menudo, las plantillas son totalmente independientes, por lo que el proceso es sencillo: el contenido simplemente se copia en una nueva página de plantilla en la otra wiki y todo funciona. Sin embargo, en plantillas más complejas, la plantilla puede invocar un módulo, transcluir otras plantillas, solo funcionar si se combina con una plantilla separada o necesitar un código CSS o JavaScript particular para funcionar. En estos casos, es útil incluir una breve lista de plantillas u otro código que ésta requiera, al final de la documentación.
Al ver la página de la plantilla renderizada (a diferencia de su código wiki), lo que normalmente es visible justo debajo del título es la plantilla renderizada en sí, seguida de una sección separada para mostrar la documentación renderizada de la plantilla, seguida de las categorías a las que pertenece la plantilla. . Las categorías y documentación de cualquier tipo en una página de plantilla (incluido TemplateData ) siempre deben estar encerradas entre etiquetas noinclude , para que no aparezcan cuando la plantilla se use en otra página.
El código wiki editable para la documentación de la plantilla a menudo se coloca en una subpágina separada de la propia plantilla, que luego se incluye al final de la página de la plantilla. Esto separa el código de plantilla, a menudo complejo, de la documentación, lo que facilita la edición de la documentación y reduce la cantidad de errores de edición accidentales en el código de plantilla. También permite proteger las plantillas cuando sea necesario, limitando el acceso de edición al código de las plantillas importantes y permitiendo que cualquiera edite la documentación de esas plantillas. Este método a veces se denomina "patrón de página de documento de plantilla".
Debes poner {{ documentación }} al crear (publicar) una plantilla. Luego se crea una página de documentación con [view] [edit] [history] [purge]enlaces. Puede crear y editar la documentación de la plantilla haciendo clic en el [edit]enlace de este panel.
Las subpáginas de documentación de plantilla que utilizan {{ documentación }} se nombran y formatean utilizando el siguiente patrón general, para mayor coherencia.
Supongamos que su plantilla se llama Template:X. Edite la plantilla y agregue lo siguiente al final del código de la plantilla, o use {{subst: doc-code }}:
[--última línea del código de su plantilla--] <noinclude>{{Documentación}}<!-- ¡Agregue categorías a la subpágina /doc e interwikis en Wikidata, no aquí! --></noinclude>Esto transcluirá {{ documentación }} en la parte inferior de la página de la plantilla.
Importante : asegúrese de que la apertura <noinclude>comience inmediatamente después del último carácter del código o texto de la plantilla y no en una nueva línea ni con espacios intermedios. De lo contrario, se insertará espacio adicional debajo de la plantilla cuando se utilice, lo que normalmente no es deseado.
Si la plantilla ya está protegida, pídale a un administrador que lo haga o solicite una edición usando un en la página de discusión de la plantilla. Si la documentación y las categorías ya existen en una sección, encerradas dentro de un contenedor, muévalas a la subpágina de documentación (donde deben estar encerradas ), ya que es mejor no dividir la documentación en dos páginas separadas.{{edit protected}}<noinclude>...</noinclude><includeonly>...</includeonly>
Utilice [create]el enlace en la parte inferior del cuadro de documentación vacío para crear automáticamente una subpágina de documentación precargada . Inserte la documentación después de la línea superior y las categorías debajo de la línea de comentario correspondiente, dejando el comentario en su lugar, para que el diseño se conserve cuando se edite la página en el futuro. Se pueden vincular plantillas relacionadas, páginas de políticas, proyectos, etc. agregando una sección "Ver también". Guarde la subpágina.
Para crear la subpágina de documentación manualmente, cree una subpágina con el nombre Template:X/doc. Vea los detalles en {{ Subpágina de documentación }} o inicie la página copiando y pegando el siguiente wikitexto estándar:
{{ Subpágina de documentación }} == Uso ==< includeonly >{{ Sandbox otro || <!-- Categorías debajo de esta línea -->}}</ incluir solo >La línea superior mostrará un mensaje que explica la página actual y un enlace a la página de la plantilla. Guarde la subpágina y siga las instrucciones de la sección "Usar plantilla:Documentación".
En lugar de escribir manualmente un gráfico principal y una tabla de uso, la plantilla {{ Format TemplateData }} puede hacer la mayor parte del trabajo. Simplemente escriba su TemplateData en la interfaz de la tabla y luego envuélvalo en una llamada de plantilla como {{Format TemplateData|1=<templatedata>...</templatedata>}}en la parte superior de la página.
Es posible que desees redirigir la página de discusión de la subpágina /doc a la página de discusión de la propia plantilla. Entonces, toda la conversación relacionada con la plantilla y su documentación terminará en la misma página de conversación. Por ejemplo, redirija Template talk:X/doca Template talk:X.
Una página de documentación también se puede redirigir a la subpágina /doc de otra plantilla, si eso cubre el uso de ambas plantillas. En este caso, al hacer clic en los enlaces para ver o editar la documentación se abrirá directamente el destino de la redirección. Si es necesario acceder al redireccionamiento en sí (por ejemplo, para eliminar el redireccionamiento y crear una página de documento separada), vaya a la URL de la plantilla haciendo clic en la barra de ubicación en la parte superior de su navegador y agregue /doc al final.
Para generar una plantilla en blanco, que luego se puede copiar de la documentación y pegar en otra página, utilice:
{{subst:#tag:pre|{{subst:Parameters|code|base={{subst:BASEPAGENAME}}}}|style=overflow: auto;}}Para generar una instancia de la plantilla, completada con sus propios nombres de propiedad, use:
{{subst:Parameters|demo|base={{subst:BASEPAGENAME}}|_base=}}[[Category:Category name]]código dentro de una <includeonly>...</includeonly>sección en la subpágina del documento .[[Category:Category name]]código dentro de una <noinclude>...</noinclude>sección en la subpágina del documento .[[Category:Category name]]código dentro de una <includeonly>...</includeonly>sección en la página de la plantilla. La ubicación exacta dentro del código de la plantilla puede afectar la forma en que se ejecuta el código de categoría.Antes de realizar cambios en una plantilla, puede ser bueno copiar primero el código de la plantilla en un entorno limitado y ejecutar algunos casos de prueba, ya que la plantilla puede ser visible en miles o incluso millones de páginas. Si crea subpáginas llamadas exactamente " /sandbox " y " /testcases " para una plantilla, el cuadro verde {{documentation}}de la plantilla lo detectará automáticamente y mostrará enlaces a esas páginas en su encabezado. Consulte Wikipedia: Sandbox de plantillas y casos de prueba para obtener más información.
Cuando varias plantillas funcionan juntas o son muy similares, suele ser más claro y fácil mantener una única página de documentación que las documente juntas. La forma más sencilla de hacer esto es crear una página de documentación completa en una de las plantillas y luego realizar "redirecciones suaves" desde las otras plantillas. Véase, por ejemplo: {{ wrap }}.
Cuando no se ha creado una subpágina de documentación y la plantilla se utiliza con un parámetro en la página de plantilla real, para colocar la plantilla en una categoría, agréguela dentro de la plantilla de documentación, después del contenido. Por ejemplo, para colocarlo en la página de plantilla real:{{documentation}}|content=[[Category:Category name]]
<!--Última línea del código de su plantilla--> < noinclude > {{ Documentación | contenido = <!-- documentación de plantilla -->[[ Categoría : Nombre de la categoría ]] [[ Categoría : Nombre de la categoría2 ]] }}</ noinclude >Cuando una plantilla como la que se muestra se vincula a una página que puede servir como documentación, entonces la documentación separada es superflua y no es necesario crearla. Por ejemplo, una plantilla de código auxiliar, que utiliza la plantilla {{ asbox }} como base, ya mostrará documentación común precargada para todas las plantillas de código auxiliar que usan esa plantilla y no necesitará documentación adicional.
A continuación se ofrecen algunos consejos para facilitar la redacción de documentaciones:
<ref group="note">...</ref>se pueden insertar fácilmente con {{ tag }}. Este ejemplo está escrito como {{ tag |ref|params=group="note"}}<nowiki />etiqueta única:[[<nowiki />example]]se convierte en [[ejemplo]],[<nowiki />http://en.wikipedia.org no link]es [http://en.wikipedia.org sin enlace]. Consulte WP:NOWIKI para obtener más detalles.{{cat|Templates with incorrect parameter syntax}}se convierte en Categoría:Plantillas con sintaxis de parámetros incorrecta .< includeonly >{{ sandbox otro ||{{ testcases otro || <!-- Categorías debajo de esta línea, por favor; interwikis en Wikidata -->}}}}</ incluir solo >{{ Alguna plantilla de cuadro de información (secundario) | niño = <includeonly> sí </includeonly> | _ _ _ _ etiqueta1 = Hola | data1 = Mundo }}< noinclude >{{ documentación }}</ noinclude >