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?
Steve
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.
On 20/04/06, Ilmari Karonen nospam@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
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
On 4/20/06, Tim Starling t.starling@physics.unimelb.edu.au wrote:
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.
Can a template transclude itself inside a <noinclude> section? In other words, would documentation that contains an example of the template in use (very useful for infoboxes, for example) parse properly if placed on the template itself, rather than its talk page?
Kirill Lokshin
On 20/04/06, Kirill Lokshin kirill.lokshin@gmail.com wrote:
Can a template transclude itself inside a <noinclude> section? In other words, would documentation that contains an example of the template in use (very useful for infoboxes, for example) parse properly if placed on the template itself, rather than its talk page?
Yes, as I discovered this morning, but it's confusing as all hell to actually create those examples. See: http://en.wikipedia.org/wiki/User:Stevage/templatetest
Example of confusion: I just edited it to add a couple of words. When I save, I don't see those words. When you edit it, they show up in the preview. If you save it again, they'll show up.
So basically, you just an extra blank save after every change to get changes to propagate through to the examples.
Steve
On 4/21/06, Tim Starling t.starling@physics.unimelb.edu.au wrote:
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.
That sounds like an excellent way to go. It will be visible from the template page, and editable in its own place, away from both the actual template code and the talk page discussion.
-- Stephen Bain stephen.bain@gmail.com
On 20/04/06, Stephen Bain stephen.bain@gmail.com wrote:
That sounds like an excellent way to go. It will be visible from the template page, and editable in its own place, away from both the actual template code and the talk page discussion.
Shall we propose a naming convention? Possibilities:
/help /documentation /doc /usage
Steve
Steve Bennett wrote:
On 20/04/06, Stephen Bain stephen.bain@gmail.com wrote:
That sounds like an excellent way to go. It will be visible from the template page, and editable in its own place, away from both the actual template code and the talk page discussion.
Shall we propose a naming convention? Possibilities:
/help /documentation /doc /usage
/etc/man?
On 4/21/06, Alphax (Wikipedia email) alphasigmax@gmail.com wrote:
Steve Bennett wrote:
On 20/04/06, Stephen Bain stephen.bain@gmail.com wrote:
That sounds like an excellent way to go. It will be visible from the template page, and editable in its own place, away from both the actual template code and the talk page discussion.
Shall we propose a naming convention? Possibilities:
/help /documentation /doc /usage
/etc/man?
No, no, no. Everyone knows documentation goes in the /usr/share/doc hierarchy! /etc/man would be for configuring the software used to view the documentation, and we all know that MediaWiki configuration goes in /etc/Special: Sheesh. What a n00b.
~maru
I don't like your unix-centrism. \readme.txt
Steve
On 21/04/06, maru dubshinki marudubshinki@gmail.com wrote:
On 4/21/06, Alphax (Wikipedia email) alphasigmax@gmail.com wrote:
Steve Bennett wrote:
On 20/04/06, Stephen Bain stephen.bain@gmail.com wrote:
That sounds like an excellent way to go. It will be visible from the template page, and editable in its own place, away from both the actual template code and the talk page discussion.
Shall we propose a naming convention? Possibilities:
/help /documentation /doc /usage
/etc/man?
No, no, no. Everyone knows documentation goes in the /usr/share/doc hierarchy! /etc/man would be for configuring the software used to view the documentation, and we all know that MediaWiki configuration goes in /etc/Special: Sheesh. What a n00b.
~maru _______________________________________________ WikiEN-l mailing list WikiEN-l@Wikipedia.org To unsubscribe from this mailing list, visit: http://mail.wikipedia.org/mailman/listinfo/wikien-l
On 4/21/06, Steve Bennett stevage@gmail.com wrote:
I don't like your unix-centrism. \readme.txt
Steve
Hmmph. At least my templates don't crash, are edittable, and aren't infected with more typos than a 3-bit whore...
~maru
On 21/04/06, maru dubshinki marudubshinki@gmail.com wrote:
On 4/21/06, Steve Bennett stevage@gmail.com wrote:
I don't like your unix-centrism. \readme.txt
Steve
Hmmph. At least my templates don't crash, are edittable, and aren't infected with more typos than a 3-bit whore...
You really haven't seen some of the more impressive meta-templates, is all I can say.
-- - Andrew Gray andrew.gray@dunelm.org.uk
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?
I've been thinking about introducing a tag which specifies that the source of the template should be displayed when you view the template page. There are a lot of meta-templates around where conversion to HTML with their default parameter values substituted in doesn't really tell you much about them. This would replace most uses for <includeonly>. Any comments on that?
In any case, I would recommend documenting templates using <noinclude> sections, as long as the formatting is such that it is clear where the template stops and the documentation begins. I think that would be an improvement for usability, over using the talk page. The server overhead should be negligible (6ms per 100KB).
-- Tim Starling
On 20/04/06, Tim Starling t.starling@physics.unimelb.edu.au wrote:
I've been thinking about introducing a tag which specifies that the source of the template should be displayed when you view the template page. There are a lot of meta-templates around where conversion to HTML with their default parameter values substituted in doesn't really tell you much about them. This would replace most uses for <includeonly>. Any comments on that?
Sounds great. Have a look at {{clearleft}} which I just "documented". Such a tag would be very useful for templates like that.
In any case, I would recommend documenting templates using <noinclude> sections, as long as the formatting is such that it is clear where the template stops and the documentation begins. I think that would be an improvement for usability, over using the talk page. The server overhead should be negligible (6ms per 100KB).
Cool. (this is the template section)<noinclude> ---- This is the documentation section.</noinclude>
Work for you?
Steve
On 20/04/06, Tim Starling t.starling@physics.unimelb.edu.au wrote:
I've been thinking about introducing a tag which specifies that the source of the template should be displayed when you view the template page. There are a lot of meta-templates around where conversion to HTML with their default parameter values substituted in doesn't really tell you much about them. This would replace most uses for <includeonly>. Any comments on that?
Actually, to be honest, the best solution in most cases is probably to show both the source *and* the rendered code. Maybe the way to do that would be a __TEMPLATESOURCE__ tag, sort of like this:
<div style="clear: left; float: left"></div> __TEMPLATESOURCE__
which would produce HTML roughly like
<div style="clear: left; float: left"> <H1>Code for this template:</H1> <code><div style="clear: left; float: left"></code>
Admittedly, there is no benefit in showing the rendered template in this case. But in others it's probably more helpful.
Steve