On Wed, Feb 24, 2010 at 07:16:32PM -0600, Rajko M. wrote:
On Wednesday 24 February 2010 12:05:27 Petr Uzel wrote:
1. Every template (except a few - more on this below) in wiki.o.o instance now has its /doc subpage with information about how to use the template (code), general description, where to use it/not to use it and in some cases there is also list of related templates. The documentation could definitely not perfect, but IMHO it is a good start to having general policy that every template should be documented.
NavBar is one too many :) The name violates convention not to use CamelCase and keeping exceptions to the accepted rules at minimum is one way to help new editors. One thing lesser to remember when they start for the first time.
I agree with you on keeping the number of exceptions as low as possible. But I don't get the point with NavBar - this was already renamed to 'Nav bar' a week ago. But there was TemplateNav, which I've just renamed to 'Template nav'.
2. It seems nobody has objections against making it policy that every $template has to be documented in $template/doc, so I'll mention it in [2] (this is yet to be done if nobody raises objections).
Yes, it should go in template creation rules/conventions.
OK, I will update it.
3. The exceptions for which I did not make /doc subpage, as mentioned in point 1, are: Template:App \ Template:Appg | Template:Appk +-> I don't understand what are these good for Template:Appj /
IMHO, they useless. It is yet another new wiki editor trying to save typing using templates.
I'll delete them. [...]
Template:Meeting - marked as 'template to rethink', looks useless to me
Interesting is how it landed on new wiki. In old wiki it was used until February 2009. It doesn't bring anything that you can't find on meeting pages. My vote is to get rid of it now.
Will do.
Template:Infobox software, Template:Information: these two templates look very similar, I don't get the difference. Are both really needed? That is one of duplicate templates that should be fixed on old wiki, but it was transferred during initial experiments with new wiki as part of Category:Education.
"Infobox software" is to some extent good name/title, at least it is common on Wikipedia.
Without knowing some context or looking into the template, I would have no clue what such template might be used for.
"Information" is good only for disambiguation page, or in Template namespace as name of template that is base for other templates.
IMO, merge both to "Infobox software", and remove category Education form the template.
But this will break pages that use these templates after they are moved from en.o.o, right? Is fixing 'incompatibilities with changed templates' part of the transition plan?
4. TOCRight template: do we really need this? In en.o.o, only a few pages use this template and IMHO it doesn't look very nice.
It also doesn't play nice with the rest of the page. We usually use tables to limit size of the Table of content (TOC).
So drop it?
5. The templates related to portals were taken from wikipedia, where these templates are also perfectly documented. IMO it would be useless to copy their documentation to wiki.o.o, so I've basically just linked the documentation to our wiki.
That is good if we update templates with Wikipedia, but if we will keep them as they are, then copy is probably better option. This is valid for anything that we use from other sources, but so far I know we still don't have this written as policy.
Henne, you ported these templates. Would you prefer to do the documentation yourself?
6. There are several navigation bar templates in the wiki. I think these templates might be placed into something like [[Category:NavBars]], so it would be easier to find proper Navbar when creating new article. Wikipedia uses something similar. What do you think?
+1 Besides we can use full name for category so that reader can see what it is about without reading description, like you already used for: http://wiki.opensuse.org/Category:Template_documentation sub Category:Navigational templates sub Category:Navigational bars
Sorry, I don't think I understand what you mean here. Could you please elaborate on this a bit? [...]
8. ATM, the documentation of a template is displayed below the template content, which is fine for small templates like AI [3], but isn't so fine for bigger templates like Article boilerplate [4]. If the user opens [4], the documentation should be better visible. I see two options, none of them ideal: a) put the documentation above the template content b) make the template content <includeonly>, so only the documentation would be visible, but then it couldn't be used as an example of recommended article layout. Any ideas?
We have to address this more thoroughly. Current article template is: 1) meant for only one type of article, user help; we have other topics that may not need this kind of template, or need different type; 2) it is all in one: template, help and sample layout; we have to break this in pieces to make it easier to use.
I agree that more specialized boilerplates would be nice. Regarding documentaion of boilerplates, Henne pointed out that it can not be documented using <noinclude>{{{{PAGENAME}}/doc}}</noinclude>, because this gets substituted to newly created article (I thought noinclude works for substitution as well). I don't know if this can be worked around (and if it is actually desired). For this reason, I've removed that snippets from the three boilerplates. Feel free to delete [Template:Article/doc] and the two others if you think it's not useful anymore.
9. Template:{Torrent, Video} These two templates were implemented using titled-click-external template, which a) isn't in wiki.o.o b) is deprecated according to Wikipedia So I've reworked Video and Torrent templates using [[image:Video.png|22px|link={{{1}}}]] syntax. It should work the same way as before except that it now adds another icon representing external link [5]. [...] I deleted the rest of templates that used depreciated "Titled click" template, those 2 somehow survived. With new format for File (Image) anyone can add any link to any image, so workaround templates based on "Titled click" are not needed anymore.
Yes, anyone can use [Image:foo|link=bar], but using {{Video|http://link.to.avi}} looks simpler to me.
Do we have any other use case for such templates?
The use cases in e.g. http://en.opensuse.org/FOSDEM2008 are sane IMHO. Petr -- Petr Uzel, openSUSE Boosters Team IRC: ptr_uzl @ freenode