De Wikipedia, la enciclopedia libre
Saltar a navegación Saltar a búsqueda

Las plantillas son una característica muy poderosa de MediaWiki , pero pueden ser 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 la 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 la plantilla, que incluye a muchos colaboradores experimentados que centran su atención en otra parte, pueda usarla 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 la documentación de la plantilla no concuerden con los estándares y principios establecidos de la comunidad. 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 lo hay, a diferencia de las políticas de Wikipedia que han sido minuciosamente examinadas por la comunidad (consulte WP: Consenso local para más detalles).

Que incluir

La documentación de la plantilla debe cubrir:

  • El propósito básico de la plantilla: qué hace y si no es inmediatamente obvio, por qué debe hacerse. Si hay otras plantillas con nombres o propósitos similares, es una buena idea mencionarlas para reducir la posibilidad de que se use la incorrecta. Incluya limitaciones importantes , como la falta de {{ visibilidad de Navbox }} en el sitio web móvil, si una plantilla solo debe usarse para ciertos países o períodos de tiempo, u otras cosas que los editores deben saber antes de elegir usar la plantilla.
  • Los parámetros de la plantilla: si están numerados, nombrados u opcionales y, de ser así, cuáles son los valores predeterminados y qué efecto tienen. Si un parámetro puede tomar solo un conjunto limitado de valores o está restringido de alguna manera, por ejemplo, si solo puede usar "sí", "no" o un número, esto debe explicarse claramente.
  • Ejemplos de uso : especifique el wikitexto exacto que debe usarse y el resultado que produce. El wikitexto puede incluirse en un <code>...</code>contenedor, para que quede claro y easy to copy, like this. Si la plantilla se puede utilizar de varias formas diferentes, con o sin parámetros opcionales, por ejemplo, proporcione una serie de ejemplos. Una buena forma de hacerlo es incorporar la plantilla en la documentación unas cuantas veces (es decir, usar ejemplos en vivo), con diferentes parámetros cada vez y enumerar los parámetros utilizados en cada caso. Con Template: Xpd esto se puede hacer sin poner la llamada de la plantilla dos veces en el wikitexto.
  • Etiquetas TemplateData : consulte Wikipedia: TemplateData / Tutorial .
  • Plantillas relacionadas : si la plantilla es una de una serie de plantillas, incluya enlaces a estas; en particular, asegúrese de que todas las plantillas de la serie estén vinculadas a todas las demás, ya que esto facilita la navegación. (Una plantilla de navegación separada puede ser útil para este propósito, consulte: Plantilla: Plantillas de protección ).
  • Categorías donde corresponda (los enlaces de InterWikimedia deben aparecer en Wikidata ; más información en Wikipedia: Wikidata ). Al igual que la documentación, las categorías deben enumerarse dentro de un<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 navegar a través de ellas.

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: los contenidos simplemente se copian en una nueva página de plantillas en la otra wiki, y todo funciona. Sin embargo, en plantillas más complejas, la plantilla puede invocar un módulo, incluir 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 este requiera, al final de la documentación.

Donde colocarlo

La página de una plantilla en el espacio de nombres de la plantilla es la ubicación del código de la plantilla que controla el aspecto y el comportamiento de esa plantilla. Lo que suele aparecer debajo del título en la plantilla renderizada : página (a diferencia de la ventana de edición en la pestaña Editar o, en el caso de las plantillas cuyo código está protegido, la pestaña Ver fuente , es la plantilla renderizada en sí, seguida de una sección para mostrar la documentación renderizada de la plantilla, seguida de las categorías a las que pertenece la plantilla.

Sin embargo, el wikicode editable para la documentación de la plantilla a menudo se coloca en una subpágina separada de la propia plantilla, que luego se transcluye 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 el número de errores de edición accidentales en el código de plantilla. También permite proteger las plantillas cuando sea necesario, lo que limita el acceso de edición al código de las plantillas importantes y permite que cualquiera pueda editar la documentación de esas plantillas. Este método a veces se denomina "patrón de página plantilla-documento".

La documentación de cualquier tipo en una página de plantilla (incluidos TemplateData ) siempre debe estar incluida en un <noinclude>...</noinclude>contenedor, de modo que no aparezca cuando la plantilla se use en otra página.

Cómo crear una subpágina de documentación

Ponga documentación en la plantilla

Debe 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 mantener la coherencia.

Suponga que su plantilla tiene un nombre 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 de su código de 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á espacio adicional debajo de la plantilla cuando se use, lo que generalmente no se desea.

Si la plantilla ya está protegida, pídale a un administrador que haga esto 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 en un contenedor, muévalas a la subpágina de documentación (donde deben incluirse ), ya que es mejor no dividir la documentación en dos páginas separadas.{{edit protected}}<noinclude>...</noinclude><includeonly>...</includeonly>

Creación automática

Utilice el [create]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, de modo que el diseño se conserve cuando se edite la página en el futuro. Las plantillas relacionadas, la página de políticas, los proyectos, etc. se pueden vincular agregando una sección "Ver también". Guarde la subpágina.

Creación manual

Para crear la subpágina de documentación manualmente, 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  }} <! - Agregue categorías donde se indica en la parte inferior de esta página e interwikis en Wikidata ->== Uso ==<includeonly> {{ sandbox  otro || <! -  Categorías  debajo de  esta  línea ;  interwikis  en  Wikidata  ->}} </includeonly>

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 ".

Con TemplateData

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.

Notas

Es posible que desee redirigir la página de discusión de la subpágina / doc a la página de discusión de la propia plantilla. Entonces, todas las conversaciones relacionadas con la plantilla y su documentación terminarán en la misma página de conversación. Por ejemplo, redirigir 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 a la redirección en sí (por ejemplo, para eliminar la redirección 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.

Blanco

Para generar una plantilla en blanco, que luego se puede copiar de la documentación y pegar en otra página, use:

{{subst:#tag:pre|{{subst:Parameters|code|base={{subst:BASEPAGENAME}}}}|style=overflow: auto;}}

Ejemplos de

Para generar una instancia de la plantilla, poblada con sus propios nombres de propiedad, use:

{{subst:Parameters|demo|base={{subst:BASEPAGENAME}}|_base=}}

Categorías y enlaces interwiki

  • Para colocar la plantilla en una categoría , agregue el [[Category:Category name]]código dentro de una <includeonly>...</includeonly>sección en la subpágina del documento .
  • Para crear un enlace interwiki para la plantilla en sí , vaya a Wikidata y siga las instrucciones para agregar enlaces a las páginas.
  • Para colocar la subpágina del documento en una categoría , agregue el [[Category:Category name]]código dentro de una <noinclude>...</noinclude>sección en la subpágina del documento .
  • Para hacer que la plantilla coloque un artículo en una categoría (cuando el artículo incluye la plantilla), agregue el [[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.

/ sandbox y / testcases

Antes de realizar cambios en una plantilla, puede ser bueno copiar primero el código de la plantilla en una caja de arena 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 el nombre exacto " / 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 plantilla y casos de prueba para obtener más información.

Varias plantillas, una página de documentación

Cuando varias plantillas funcionan juntas o son muy similares, a menudo es más claro y fácil mantener una sola 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 "redireccionamientos suaves" desde las otras plantillas. Vea, por ejemplo: {{ wrap }}.

Directamente en una página de plantilla

Cuando no se ha creado una subpágina de documentación, y la plantilla {{ documentación }} se está utilizando con un |content=parámetro en la página de la plantilla real, para colocar la plantilla en una categoría, agréguela [[Category:Category name]]dentro de la plantilla de documentación, después del contenido. Por ejemplo, para la ubicación en la página de la plantilla real:

<! - Última línea de su código de plantilla -> <noinclude> {{ Documentación  |  content  = <! -  documentación de la plantilla  -> [[ Categoría : nombre de categoría  ]] [[ Categoría : nombre de categoría2 ]] }} </noinclude>

Cuando no se necesita documentación

Cuando una plantilla como se muestra se vincula a una página que puede servir como documentación, 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.

Consejos y trucos

A continuación, se ofrecen algunos consejos para facilitar la redacción de documentación:

  • Se pueden insertar enlaces a plantillas como {{ año japonés | 1800}} escribiendo {{ tlp | año japonés | 1800}} . Consulte {{ tlp }} para obtener plantillas similares.
  • Las etiquetas HTML como <ref group="note">...</ref>se pueden insertar fácilmente con {{ tag }}. Este ejemplo está escrito como {{ tag | ref | params = group = "note"}}
  • Signo igual = se puede insertar con {{=}} . Por ejemplo, {{ Citación necesaria | fecha = 1900-02-29}} se realiza antes del {{ tlp | Citación necesaria | fecha {{=}} 1900-02-29}} . Evite la notación equivalente & # 61; que no es fácil de leer para otros editores.
  • No olvide la <nowiki />etiqueta única . [[ <nowiki />ejemplo]] se convierte en [[ejemplo]] y [ <nowiki />http://en.wikipedia.org sin enlace] es [ http://en.wikipedia.org sin enlace]. Consulte WP: NOWIKI para obtener más detalles.
  • Para un enlace a una categoría, use {{ cat }}. Por ejemplo, {{ cat | Plantillas con sintaxis de parámetro incorrecta}} se convierte en Categoría: Plantillas con sintaxis de parámetro incorrecta .
  • Para suprimir la categorización de las páginas / sandbox y / testcases de la plantilla (si existen), use este código en la parte inferior de la subpágina de documentación:
<includeonly> {{ sandbox  otro || {{ casos de prueba  otros || <! -  Categorías  debajo de  esta  línea ,  por favor ;  interwikis  en  Wikidata  ->}}}} </includeonly>
  • Cuando la plantilla es un cuadro de información secundario , la documentación aparece rota. Evite esto agregando la etiqueta <includeonly>:
{{Alguna plantilla de infobox (secundaria)| child = <includeonly> yes </includeonly>| label1 = Hola| data1 = Mundo}} <noinclude> {{documentación}} </noinclude>

Ver también

  • {{ Documentation }}: incluye la documentación en la página de la plantilla y proporciona vínculos de visualización, edición e historial de la documentación.
  • {{ Subpágina de documentación }}: explica que lo que sigue es documentación y enlaces a la página documentada.
  • <noinclude> y <includeonly>
  • {{ Mejorar la documentación }}
  • {{ Tag }}: uso global
  • {{ Lista de referencias de plantillas }}
  • {{ WPBannerDoc }}: para plantillas de WikiProject
  • Wikipedia: plantillas de alto riesgo
  • Wikipedia: caja de arena de plantilla y casos de prueba