[WikiEN-l] Template documentation convention

[Tim Starling]

Ilmari Karonen wrote:
> Steve Bennett wrote:
> 
>>Hi all,
>>  Anyone know if there is a convention/guideline for how to document
>>templates, given the existence of <noinclude>? Previously, the
>>discussion page was used. Now it would seem more appropriate to move
>>documentation onto the main template page, inclosed within
>><noinclude>. However, before launching into doing this, two questions:
>>
>>* Is there consensus for this?
>>* Is there more of a burden on the surver to transclude a template
>>which includes a large amount of <noinclude>'d documentation?
> 
> 
> Any edits to the template itself, even to <noinclude> sections, force a 
> purge of every page using the template.  For widely used templates, this 
> may be a significant cost.  Thus, I'd recommend keeping only the most 
> basic and stable documentation on the template page itself, and put the 
> rest on the talk page.  In fact, for the majority of templates, the only 
> "documentation" needed on the template page is the default rendering of 
> the template code itself.
> 
> But that's just my opinion.
> 

Oh yeah, except for that. Well, you can always transclude the talk page or a documentation subpage
from within a <noinclude> section. Because <noinclude> suppresses link registration, updates to the
documentation subpage won't cascade down to the actual articles.

-- Tim Starling