On Wednesday 24 February 2010 12:05:27 Petr Uzel wrote:
Hi, I've spent some time working on documenting the templates in wiki.o.o as suggested in [1], so here is small report and some random thoughts:
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.
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.
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. Besides, titles violate custom not to use words and abbreviations that are in common use in many topics, like here App (application), that many project may want to use and it is good only as title of disambiguation page. Also it violates another rule, not to use cryptic names like Appg, Appk, Appj, that no one in the world can guess what they stand for. I guess even author after some time will have trouble to answer the question:"What is AppX ?"
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.
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. "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.
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).
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.
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
7. I've fixed capitalization of categories, so all the categories now follow the naming conventions.
Thanks :)
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. To skip explanation, I'll try to come up with some illustration what I mean.
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 don't know how to get rid of this icon (does it mind actually??), so if ((this is not desired && can not be fixed) || (there are some other drawbacks I didn't notice)), then please revert these two templates back.
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. Do we have any other use case for such templates?
[1] http://lists.opensuse.org/opensuse-wiki/2010-02/msg00055.html [2] http://wiki.opensuse.org/Help:Template [3] http://wiki.opensuse.org/Template:AI [4] http://wiki.opensuse.org/Template:Article [5] http://wiki.opensuse.org/User:Puzel/Test
Petr
-- Petr Uzel, openSUSE Boosters Team IRC: ptr_uzl @ freenode
-- Regards Rajko, -- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-wiki+help@opensuse.org