Bureaucrats, Moderators (CommentStreams), Interface administrators, Push subscription managers, Suppressors, Administrators
12,446
edits
Saintapedia:Template documentation: Difference between revisions
Saintapedia:Template documentation (view source)
Revision as of 03:32, 27 September 2025
, 27 Septemberno edit summary
(Created page with "= Saintapedia:Template Documentation for Portal:Homepage = This page provides documentation for templates used on the Portal:Homepage of Saintapedia. Templates are reusable components that help structure and standardize content across the wiki, particularly for organizing information about saints, parishes, dioceses, and Catholic demographics. This guide explains how to use these templates, including the `{{Documentation subpage}}` mechanism, and provides instructio...") |
No edit summary |
||
| Line 1: | Line 1: | ||
= Saintapedia:Template Documentation | = Saintapedia:Template Documentation = | ||
This page provides documentation for templates | This page provides guidance for creating and maintaining documentation for all templates on Saintapedia. Templates are reusable components that standardize content presentation, simplify editing, and support dynamic data display (e.g., via Cargo tables) for topics like saints, parishes, dioceses, and Catholic demographics. Proper documentation ensures templates are easy to use and maintain. This guide explains the `{{Documentation subpage}}` template and best practices for documenting any template on the wiki. | ||
== Purpose of | == Purpose of Template Documentation == | ||
Template documentation explains how a template works, its parameters, and how to use it correctly. It is typically hosted on a subpage (e.g., `Template:<TemplateName>/doc`) and linked from the template page. Documentation is essential for: | |||
* Clarity: Helping editors understand the template’s purpose and usage. | |||
* Consistency: Ensuring templates are used uniformly across Saintapedia. | |||
* Collaboration: Encouraging editors to improve templates via talk pages or sandboxes. | |||
* Maintenance: Simplifying updates, especially for templates using Cargo or other extensions. | |||
== Using {{Documentation subpage}} == | |||
The `{{Documentation subpage}}` template marks a page as the documentation for a specific template. It is placed at the top of a subpage (e.g., `Template:Example/doc`) to indicate its purpose and provide navigation links. | |||
== | * '''Usage''': | ||
<pre>{{Documentation subpage}}</pre> | |||
Place this at the start of the documentation subpage. It displays a notice stating that the page documents a template, with links to the template, its talk page, and (if available) sandbox or testcases. | |||
* '''Purpose''': | |||
* Clarifies that the page is documentation, not a standalone article. | |||
* Encourages editors to discuss improvements on the template’s talk page. | |||
* Supports testing in a sandbox to avoid breaking live templates. | |||
* '''Example''': For a template named `{{Infobox saint}}`, the documentation page at `Template:Infobox saint/doc` would start with: | |||
<pre>{{Documentation subpage}}</pre> | |||
Followed by sections explaining the template’s purpose, parameters, and usage. | |||
== Creating Template Documentation == | |||
To create documentation for any template on Saintapedia: | |||
1. Create the Documentation Subpage: | |||
* | * Navigate to `Template:<TemplateName>/doc` (e.g., `Template:Infobox saint/doc`). | ||
* | * If it doesn’t exist, create the page by editing it. | ||
* Add `{{Documentation subpage}}` at the top. | |||
2. Structure the Documentation: | |||
* | Use the following standard format: | ||
* Purpose: Describe what the template does (e.g., “Displays a standardized infobox for saint biographies”). | |||
* Usage: Provide the basic syntax (e.g., `{{TemplateName|parameter1|parameter2}}`). | |||
* Parameters: List all parameters, their purpose, and whether they are optional or required. Use a table or bullet points for clarity. | |||
* Examples: Show how the template renders with sample inputs. | |||
* Notes: Highlight dependencies (e.g., Cargo tables, specific extensions), common issues, or styling tips. | |||
Example structure for `Template:Infobox saint/doc`: | |||
<pre> | |||
{{Documentation subpage}} | |||
== Purpose == | |||
The {{Infobox saint}} template creates a standardized infobox for saint biographies, displaying key details like feast day, patronage, and birth/death dates. | |||
== | == Usage == | ||
<pre>{{Infobox saint | |||
| name = | |||
| feast_day = | |||
| patronage = | |||
}}</pre> | |||
== | == Parameters == | ||
The | * name – The saint’s name (required). | ||
* feast_day – The saint’s feast day (optional). | |||
* patronage – Areas or groups the saint is patron of (optional). | |||
== Example == | |||
{{Infobox saint | |||
| name = Saint Francis of Assisi | |||
| feast_day = October 4 | |||
| patronage = Animals, Italy | |||
}} | |||
Produces: [Infobox rendering] | |||
== | == Notes == | ||
* Ensure dates follow Saintapedia’s style guide (e.g., “October 4” not “4 October”). | |||
* Use Cargo queries for dynamic fields like parish lists, if applicable. | |||
[[Category:Template documentation]] | |||
</pre> | |||
3. Link to Documentation: | |||
* Add `{{Documentation}}` to the bottom of the template page (e.g., `Template:Infobox saint`) to display the documentation subpage content. | |||
* Use `<noinclude>{{Documentation}}</noinclude>` to ensure it only appears on the template page, not where the template is transcluded. | |||
4. Use VisualEditor or Wikitext: | |||
* Saintapedia supports VisualEditor for ease of use, but wikitext is recommended for precise control in template documentation. | |||
* Use “Show preview” to check formatting before saving. | |||
5. Test Changes: | 5. Test Changes: | ||
* Create a sandbox (e.g., `Template:<TemplateName>/sandbox`) to test template modifications. | |||
* Use testcases (e.g., `Template:<TemplateName>/testcases`) to compare outputs. | |||
* Verify functionality on a test page before applying changes to live templates. | |||
== Best Practices == | == Best Practices == | ||
* Be Clear and Concise: Write documentation that is | * Be Clear and Concise: Write documentation that is accessible to new editors while including technical details for advanced users. | ||
* | * Standardize Formatting: Follow a consistent structure (Purpose, Usage, Parameters, Examples, Notes) for all template documentation. | ||
* Leverage Cargo: For templates using Cargo tables (e.g., for saint or parish data), explain how to query or update data. Reference [[Help:Cargo]] for details. | |||
* Check | * Check Dependencies: Ensure linked files (e.g., images) or extensions (e.g., Cargo) are functional. Report broken links to administrators. | ||
* Encourage Collaboration: Invite editors to discuss improvements on the template’s talk page. | * Encourage Collaboration: Invite editors to discuss improvements on the template’s talk page or join [[Saintapedia:WikiProject]]. | ||
* Categorize Documentation: Add `[[Category:Template documentation]]` to all documentation subpages for easy navigation. | |||
== Troubleshooting == | == Troubleshooting == | ||
* Broken File Links: | * Template Not Rendering: Check for syntax errors, missing parameters, or changes in transcluded templates. | ||
* Cargo Query Issues: Ensure Cargo tables are | * Broken File Links: Verify that images (e.g., icons used in templates) exist in the file library. Upload replacements if needed. | ||
* | * Cargo Query Issues: Ensure Cargo tables are defined and populated correctly. Use Cargo drilldown to test queries. | ||
* | * VisualEditor Errors: Switch to wikitext mode if VisualEditor introduces formatting issues. | ||
* Documentation Not Displaying: Confirm that `{{Documentation}}` is included in the template page and that the `/doc` subpage exists. | |||
== Examples of Common Templates == | |||
Below are examples of templates you might document on Saintapedia: | |||
* Infobox Templates: `{{Infobox saint}}`, `{{Infobox parish}}` – For structured data display. | |||
* Navbox Templates: `{{Saints by country}}` – For navigation links grouping related content. | |||
* Cargo Query Templates: `{{Saints by region}}` – For dynamic lists using Cargo tables. | |||
* Utility Templates: `{{Cite web}}` – For consistent citation formatting. | |||
For each, create a `/doc` subpage with `{{Documentation subpage}}` and follow the structure outlined above. | |||
== See Also == | == See Also == | ||
* [[Help: | * [[Help:Templates]] – General guide to creating and using templates. | ||
* [[Help: | * [[Help:Cargo]] – Documentation for Cargo queries used in dynamic templates. | ||
* [[Help: | * [[Help:Editing Saintapedia]] – Instructions for editing with VisualEditor or wikitext. | ||
* [[Saintapedia:WikiProject]] – Collaborate on improving Saintapedia’s templates and content. | * [[Saintapedia:WikiProject]] – Collaborate on improving Saintapedia’s templates and content. | ||
[[Category:Saintapedia documentation]] | [[Category:Saintapedia documentation]] | ||
[[Category:Template documentation]] | [[Category:Template documentation]] | ||