[WikiEN-l] Template documentation convention

[Steve Bennett]

On 20/04/06, Ilmari Karonen <nospam at vyznev.net> wrote:
> 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.

That's certainly true, but unless you're talking about the cost of the
documentation frequently changing, I suspect that's a pretty
negligible cost.  In extreme cases, perhaps a link to the talk page
would be appropriate - going to the "discussion" page for
documentation is, IMHO, extremely non-intuitive. In fact, I still fall
into the trap of thinking a template is not documented at all when
there is nothing on the actual template page.

Another solution in some cases might be to make a subpage called
/help, and then to include that subpage into the main page. But on
second thoughts maybe that doesn't solve the problem of page purging
when the doc updates...

Steve