Las plantillas son una característica muy potente de MediaWiki , pero pueden resultar confusas para los usuarios nuevos 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 la usabilidad.
La documentación de las plantillas debe explicar qué hace una plantilla y cómo utilizarla. Debe ser lo suficientemente sencilla como para que un usuario sin un conocimiento completo de las complejidades de la sintaxis de las plantillas (lo que incluye a muchos colaboradores experimentados que centran su atención en otras áreas) pueda utilizarla correctamente. Esto es especialmente cierto en el caso de plantillas muy utilizadas.
Los editores deben respetar las políticas o pautas oficiales cuando las páginas de documentación de plantillas sean incompatibles con los principios y estándares establecidos por la comunidad. Los editores también deben evitar "citar" las páginas de documentación de plantillas como si fueran políticas, incluida esta guía de instrucciones . Las páginas de documentación de plantillas se pueden escribir sin mucho debate (si es que hay alguno), a diferencia de las políticas de Wikipedia que han sido examinadas exhaustivamente por la comunidad (consulte WP:Consenso local para obtener 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 formas, con o sin parámetros opcionales, por ejemplo, proporcione una variedad de ejemplos. Una buena forma de hacerlo es incluir la plantilla en la documentación unas cuantas veces (es decir, utilizar ejemplos en vivo), con diferentes parámetros cada vez y enumerar los parámetros utilizados en cada caso. Con {{ demo }} esto se puede hacer sin poner la llamada a la plantilla dos veces en el wikitexto.<noinclude>...</noinclude>contenedor en una plantilla o dentro<includeonly>{{Sandbox other||...}}</includeonly>de 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 completamente independientes, por lo que el proceso es fácil: simplemente se copian los contenidos a 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 esta requiera, al final de la documentación.
Al visualizar la página de la plantilla renderizada (en lugar de su código wiki), lo que suele verse justo debajo del título es la plantilla renderizada, 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 la documentación de cualquier tipo en una página de plantilla (incluido TemplateData ) siempre deben estar encerradas entre etiquetas noinclude , de modo que no aparezcan cuando la plantilla se use en otra página.
El código wiki editable para la documentación de la plantilla se coloca a menudo 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 la plantilla, a menudo complejo, de la documentación, lo que hace que la documentación sea más fácil de editar y reduce la cantidad de errores de edición accidentales en el código de la plantilla. También permite proteger las plantillas cuando sea necesario, lo que limita el acceso de edición al código de plantillas importantes y permite que cualquiera edite la documentación de esas plantillas. Este método a veces se conoce como "patrón de página plantilla-documento".
Debes poner {{ documentation }} al crear (publicar) una plantilla. Luego se crea una página de documentación con [view] [edit] [history] [purge]enlaces. Puedes crear y editar la documentación de la plantilla haciendo clic en [edit]el enlace de este panel.
Las subpáginas de documentación de plantillas que utilizan {{ documentation }} se nombran y formatean utilizando el siguiente patrón general, para mantener la coherencia.
Supongamos que su plantilla se llama Template:X. Edite la plantilla y añada lo siguiente al final del código de la plantilla o utilice {{subst: doc-code }}:
[--última línea del código de tu plantilla--] <noinclude>{{Documentación}}<!-- ¡Agregue categorías a la subpágina /doc e interwikis en Wikidata, no aquí! --></noinclude>Esto incluirá {{ 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á un espacio adicional debajo de la plantilla cuando se utilice, lo que generalmente no es deseable.
Si la plantilla ya está protegida, pídale a un administrador que lo haga o solicite una edición mediante 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, dentro de un contenedor, muévalas a la subpágina de documentación (donde deben estar encerradas entre ), ya que es mejor no tener la documentación dividida en dos páginas separadas.{{edit protected}}<noinclude>...</noinclude><includeonly>...</includeonly>
Utilice [create]el enlace que se encuentra 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 comentarios correspondiente; deje el comentario en su lugar para que se conserve el diseño cuando se edite la página en el futuro. Se pueden crear enlaces a 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 de forma manual, cree una subpágina con el nombre Template:X/doc. Consulte 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 other || <!-- Categorías debajo de esta línea -->}}</ soloincluir >En la línea superior se mostrará un mensaje explicando la página actual y un enlace a la página de 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 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 plantilla misma. De esta manera, toda la discusión relacionada con la plantilla y su documentación terminará en la misma página de discusión. Por ejemplo, redirigir Template talk:X/doca Template talk:X.
Una página de documentación también puede ser redirigida 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 a la redirección en sí (por ejemplo, para eliminar la redirección y crear una página de documentación 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, rellenada con sus propios nombres de propiedad, utilice:
{{subst:Parameters|demo|base={{subst:BASEPAGENAME}}|_base=}}[[Category:Category name]]código dentro de una <includeonly>...</includeonly>sección en la subpágina de documentación . Consulte Wikipedia:Categorización § Categorización de plantillas para obtener pautas.[[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 la categoría. Consulte Wikipedia:Categorización § Categorización mediante plantillas para obtener pautas.Antes de realizar cambios en una plantilla, puede ser conveniente copiar primero el código de la plantilla en un entorno de pruebas y ejecutar algunos casos de prueba, ya que la plantilla puede estar visible en miles o incluso millones de páginas. Si crea subpáginas con los nombres exactos " /sandbox " y " /testcases " en una plantilla, el {{documentation}}cuadro verde 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 sencillo mantener una única página de documentación que las documente juntas. La forma más sencilla de hacerlo 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 está utilizando 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 colocarla 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 la 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á la documentación común precargada para todas las plantillas de código auxiliar que utilicen esa plantilla y no necesitará documentación adicional.
A continuación se ofrecen algunos consejos para facilitar la redacción de documentación:
<ref group="note">...</ref>se pueden insertar fácilmente con {{ tag }} . Este ejemplo se escribe 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]. Ver WP:NOWIKI para más detalles.{{cat|Templates with incorrect parameter syntax}}se convierte en Category:Templates con sintaxis de parámetros incorrecta .< includeonly >{{ sandbox other ||{{ testcases other || <!-- Categorías debajo de esta línea, por favor; interwikis en Wikidata -->}}}}</ soloincluye >{{ Alguna plantilla de infobox (hijo) | hijo = < includeonly > sí </ includeonly > | etiqueta1 = Hola | datos1 = Mundo }}< noinclude >{{ documentación }}</ noinclude >