WhyNotWiki:Conventions

From WhyNotWiki

MetaWiki  edit   (Category  edit) ricacelcooub rollibodr eltorc .

Wiki conventions  edit   (Category  edit)

WhyNotWiki / Conventions  edit   (Category  edit)

Conventions and policies.

See also: MediaWiki to-do list

[edit] How this wiki is organized

The organization of this wiki is centered around topics.

I could have centered it around people and dates/timestamps (as blogs do) or keywords (as search engines do), but I think those attempts are not half as useful to anyone. It makes the most sense to me to organize around "what it's about" (in as semantic and structured a way as possible, without getting too in the way). (Many Web directories (dmoz, Yahoo, etc.) also attempt to do this, but for some reason they are not identical to my directory...)

[edit] Primary topics

Every piece of information/content needs to have a primary topic (or be its own article entirely -- remember: small pieces). So this information will go on the article page for the primary topic. Secondary topics should be indicated through the use of {{section category}}.

If it is too hard to decide on a primary topic -- perhaps multiple topics are equally applicable -- then simply create a new article just for this content snippet, and then transclude the snippet into the two or more topic articles in which this content belongs...

[edit] What goes on a page / page layout

• optional one-line description of what the page is
  • perhaps also use Template:compare template to draw attention to other related pages that writers should consider using / readers should consider looking at instead
• (collapsed) category trees for each major category to allow quick navigation to related page
• table of contents
• sections with content
• all categories

[edit] Titles: [Naming conventions (category)]

Titles: Capitalize only the first letter and all proper names.

Subpages: Put spaces around the / . Example: "MediaWiki / Questions about"

[edit] Metadata that can/should go on the page

See also Relationships database. These sections need to be merged.

• Aliases
• See also

[edit] "See also"

Use categories + CategoryTrees, or Template:Compare (?).

You can use "see also" temporarily to show the two articles are related. But this should only be a temporary measure to maintain interlinkedness until you have a chance to revisit the relationship between the two articles and aside on a more concrete/specific relationship, such as "subclass of" or "sub topic of".

It should always be possible to think of a more specific reason or way that the two are related. At least I have yet to see a worthy exception...

[edit] Aliases

The next time you come looking for this page/topic that you know it exists, you might not remember the exact name that you gave it. It may have several synonyms that would've worked equally well as the page title and one of those may come to mind instead of the actual page name. This is one place where aliases can be helpful.

Not only does this provide extra keywords to search for, it also provides documentation of which other names were considered as the title of this page. That can be useful if you later have doubts about the title and want to consider renaming it.

It also documents/draws attention to which titles are unpreferred for this page, to warn people not to use them. (Mostly to discourage the creation of duplicate pages. See next paragraph.) So in case someone was tempted to create one of those pages that is listed as an alias, they will think twice about it: "oh, I guess they are the thought of that title and they'd prefer me to just use this page instead of making a new article by that title".

This should also help prevent there from ever being duplicate pages: two separate articles that are really on (essentially... close enough... for all practical purposes) the same topic! By listing all possible aliases, we can have those aliases automatically redirect back to their preferred synonym, making it much more difficult to accidentally create a duplicate page.

• This could easily be automated ([To do: when you specify an alias for an article, automatically create an article with that alias title that redirects to the primary page]).

[edit] Categories

Categorize everything excessively. Make up new categories or guess if you're not sure which categories are available (a problem I hope to soon solve).

[edit] How to list categories

Categories shall be listed at the bottom of an article page, each on its own line.

[edit] What to put on the Category page

On the category page, it's OK to make a prominent link to the "main page" for that category.

I'm even considering this convention: Have a category page nothing more than a redirect to its main page.

• So categories would be used only for their ability to contain articles, to group articles together; the option to have a page for each category will be voluntarily [rejected]
• Solves: the problem where you click on a category link and find yourself on a useless, contentless page, from which you then have to click again and wait for the next page to load.
• This could easily be automated ([To do: when you add something to a category, automatically create a category page containing the redirect]).

Cons:

• Main page may be large and slow to load?

[edit] Too much is better than too little

I'd rather have too many categories and CategoryTrees than too few!

To not be able to find a page is a much bigger concern of mine, than to have too many ways to get to that page, to have that page be too easy to find, to have too many duplicate/redundant links to that page. I want pages to be easily findable!

[edit] CategoryTree

To help readers/editors to find related pages (and to avoid creating a duplicate page because one didn't know that the page already existed), make liberal use of the CategoryTree.

• If the article is the main page for a category, then you must insert a CategoryTree for that category!
• You may insert CategoryTrees for other "main" categories as well.

Example (toolbar link currently provided):

{{Has associated category|MetaWiki}}<categorytree mode="all" style="border:1px solid gray; padding:0.7ex;">MetaWiki</categorytree>

Having a CategoryTree on every page makes for easy navigation to related pages. It could even be compared with:

• a "see also" set
• a "site ring"

[edit] [problems (category)] Category overlap/intersection vs. new category creation

On page Traffic/transportation problems, do you create and put it in a new category (and only that category) at the intersection of 2 categories, like this?:

Traffic/transportation problems
[[Category:Traffic/transportation problems]]

Category:Traffic/transportation problems
[[Category:Traffic/transportation]]
[[Category:Problems]]

(would be more likely to do this if I didn't have to create and categorize my new category as an extra step!)

Or do you just put it in both of the categories that are intersecting and not bother creating a new category?

Traffic/transportation problems
[[Category:Traffic/transportation problems]]
[[Category:Traffic/transportation]]
[[Category:Problems]]

Or do you be extra safe and do both?

Traffic/transportation problems
[[Category:Traffic/transportation problems]]
[[Category:Traffic/transportation]]
[[Category:Problems]]

Category:Traffic/transportation problems
[[Category:Traffic/transportation]]
[[Category:Problems]]

Yipe!

[edit] [Naming conventions (category)]

[edit] Number

For example:

Category:Workstations or Category:Workstation ?

See Having an article title with a different number than its associated category

[edit] How to prevent accidentally using a synonym?

If it were normal articles we were talking about, I'd just use a redirect. But with categories, that doesn't help much, because when you add an article to a category, you don't actually go to the categories page, so we can't trigger a redirect.

I'm afraid it's all too likely for me (or anyone) to accidentally create two redundant categories simply because we couldn't remember which spelling was canonical.

For example, I can never remember if I decided I prefer Math or Mathematics, so very likely I've added some articles to one and not the other.

Now I could just create both categories and put a deprecation notice on the preferred one, pointing users to the preferred one.

That would solve one direction of the problem.

The other direction is when you are on the category page (of the preferred category): how can you find all instances of articles that were incorrectly assigned? One solution: make the non-preferred category actually a member of the preferred category. Then when you go to the preferred category, it will be listed as a subcategory. From there, if the non-preferred category has any members, you can go through them all and fix them.

Ideal solution: [To do: Have it loudly complain/auto-fix if you try to assign an article to a deprecated/non-preferred category.]

See Naming conventions.

[edit] Talk/Discussion pages

All discussion should be done on the "Talk:" pages.

You may use [this template] to add a "discuss this" link and encourage discussion.

[edit] Subpages / Context indications in titles

(Context = Parent topic = Scope = Disambiguation text)

See Naming conventions / When to use namespace/context disambiguation in a title  edit

[edit] Templates

[edit] Documenting templates / Template metadata

<noinclude>
{{{{FULLPAGENAME}}/doc}}
</noinclude>

See: http://en.wikipedia.org/wiki/Wikipedia:Template_documentation#How_to_create_a_documentation_subpage

[edit] Categorizing templates

You should add all new templates to a subcategory of Category:Templates. (If you can't decide which subcategory to put it in, don't bother putting it in any. We can always find it with the full list of templates.)

[edit] Categorizing articles that include this template

If the only reason you want to do that is so that when you make a change to the template later, you can find all the articles that might need changing (might have broken) and go through and fix/check each of them; then I offer an easier alternative:

Just use Special:Whatlinkshere!

Example: http://whynotaskwhy.com/wiki/Special:Whatlinkshere/Template:Compare

[edit] How to avoid accidentally creating a duplicate template

It would be easy to accidentally type, say, "needs sources" instead of "need sources", for example.

Search for it first or check the list of templates.

[edit] [Naming conventions (category)]

All lowercase, with spaces to separate words: {{cite web}}, not {{cite_web}} or {{cite-web}} or {{CiteWeb}}.

[edit] Avoid unwanted line breaks

Be aware that all line breaks (except those between <noinclude> tags) will be rendered in the including page.

Example of how to get around this:

<span class="plainlinks">[{{SERVER}}{{localurl:{{{1}}}}} {{{2}}}]</span> <noinclude>
...
</noinclude>

The <noinclude> being on the end of the first line above is deliberate - if it is put on the line below, then the template does not work properly and adds an unwanted line break when the template is used.

[edit] Avoid unwanted run-on lines

(In other words, how to ensure that there is a line break when there needs to be.)
[MediaWiki / Templates (category)]

MediaWiki will strip off leading and trailing whitespace from your page when you save, because it thinks it's smarter than you.

If you actually want leading whitespace in your template and you don't want MediaWiki to remove it for you, you can use this trick:

[edit] Template conventions

[edit] Categorizing templates

You should add all new templates to a subcategory of Category:Templates. (If you can't decide which subcategory to put it in, don't bother putting it in any. We can always find it with the full list of templates.)

[edit] How to avoid accidentally creating a duplicate template

It would be easy to accidentally type, say, "needs sources" instead of "need sources", for example.

Search for it first or check the list of templates.

[edit] [Naming conventions (category)]

All lowercase, with spaces to separate words: {{cite web}}, not {{cite_web}} or {{cite-web}} or {{CiteWeb}}.

[edit] Sources as their own pages

Status: This is an interim policy, to be used until I find a better solution for storing sources in MediaWiki.

Parent: Convention / Make lots of tiny articles

As soon as you think / see that a source...

• may be reused by more than one citation
• may want to have comments about it, rather than just from it
• may want to be placed in one or more categories

, you are encouraged to create a new article for that source.

[edit] [Naming conventions (category)]

The articles should be named with the prefix "Source:".

This:

• lessens the chances of name conflicts,
• reiterates to the creator and to the reader that this page is to be used for the sole purpose of representing a source,
• and may make it easier in the future to programmatically extract all information out of the Source pages into their on relational database table.
• could use MediaWiki namespaces if I wanted

Obviously, the page title needs to be unique. At the very least, it should include author: title. , preferably, it should also include the date: author: title: date.

[edit] Example

Source: Roberta Beach Jacobson: Copyrights and wrongs: 2005-01-26

Source: Tim Berners-Lee: Links and Law

[edit] How to cite these sources

need to experiment first...

[edit] Disambiguation pages

Wikipedia's Manual of Style for disambiguation pages (http://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style_%28disambiguation_pages%29). Retrieved on 2007-01-30 23:04.

[edit] Usage policy: Make lots of tiny articles and piece them together with transclusion/links

CategoryTree makes this somewhat (a lot) more feasible, because it automatically lists all the "tiny articles" (almost as if they were on the same page -- as in, much like the TOC that it auto-generates).

This will be nicer once I implement "Every link has an edit link".

[edit] Policy: Don't use category pages as content pages

No longer need to anymore now that I have CategoryTree, which can show the tree for the associated category.

Associated category for every page: So I can just have every main topic page have an associated category which acts as the container for [subpages].

Pros:

• Automatically shows CategoryTree on category pages (but we can manually put it on normal pages, so this advantage is mostly obviated)

Cons:

• Searches don't search category pages by default!!! (Can we fix that?)
• If my main page for a topic (say, "Software") were actually "Category:Software", then "Software" probably wouldn't even exist. So when I try to "go" to the page for "Software", it won't find it. It will do a search instead, but even the search won't find it because it doesn't search category pages by default!
• Difficult to upgrade normal pages to Category pages.
  • And since I can't predict which pages I might want to have category features (be containers for other pages), this problem is exacerbated.

This will be nicer if I can get it to use a template. {{CategoryTree|{{PAGE_NAME}} }} or something...will help automate this policy.

Conclusion: I'm leaning towards not using category pages for content currently, because it seems like the most MediaWiki-natural way to go. Using category pages for content would require more hacks and break more MediaWiki/Wikipedia conventions...and I'd rather just go with the flow since I can make it work the other way to my satisfaction (nearly).

Other policy: Most categories will have a main page (just strip off the "Category:" part and that's the title of it) associated with them, although they don't have to. But if you're thinking of putting content on the category page, don't; put it on the main page instead.

[edit] Talk pages

I'm not sure that I like talk pages, but I haven't disabled them, as of yet...

http://en.wikipedia.org/wiki/Template:Talkheader -- nice header

[edit] Sign your posts

http://en.wikipedia.org/wiki/Wikipedia:Sign_your_posts_on_talk_pages

[edit] Preferred synonyms / Naming conventions

See Naming conventions

[edit] Lists

For simple lists, it's usually okay just to use this format:

* item 1
* item 2

You can even provide descriptions or other extra details after the list item/item title (in which case you should probably make the item title itself be bold so it stands out and doesn't get swallowed in the sea of text on the line):

* '''Item 1''': details/description
* '''Item 2''': details/description

But if you're going to have that structure, you may as well turn it into a definition list, which helps to enforce and emphasize that structure.

;Item 1
:details/description
;Item 2
:details/description

It can also make the list more readable, because the definition is on a line by itself, and the extra whitespace can help with readability/parsability...

Item 1

details/description

Item 2

details/description

Using headings/sections:

But sometimes it's allowable/desirable to actually make a new heading/section for each item in the list:

=== Item 1 ===
...
=== Item 2 ===
...

Why? There are a couple advantages:

• It saves you from dealing with some of the limitation in MediaWiki, where, for instance, you can't put a <pre> block inside of a list item (*).
• It makes you feel like you have lots of room -- as much room as you need -- for each list item -- which makes it ideal for lists with lengthy list items.
• Each item in your list will automatically be included in the table of contents

[edit] Semantic tags only or allow HTML-ish non-semantic markup?

[draft (category)]

Ideally, we wouldn't use bold, for example, to indicate something semantic. Instead, we'd give it its own tag based on what kind of information it is -- what it means -- and use a stylesheet to decide how it gets displayed.

[edit] whether to use templates or custom parser-function tags

• Both have semantic meaning and thus are acceptable.
• We could automatically translate from one to the other

Different syntax for each: attr="what" vs. |arg=what

The main difference seems to be this: There are some things that you can't do with templates that you would need to write a parser function (extension) for if you wanted to do them.

[edit] Quotes

See Quotes for conventions governing the usage of this kind of quote; see WhyNotWiki:Citing sources for conventions governing the use of citations / longer quotes.

[edit] Mirroring pages from other wikis

[Synchronization (category)] [Mirroring (category)]

This is not yet an automated process (see Uni-directional wiki page mirroring for more about that), but currently at least there is a convention to help make the manual process more manageable.

If you just want to specify a "loose" mirror for a page or section, simply add this template to the article/section that will be periodically replaced with the contents of the source page: {{mirror of|}}.

The problem with that, however, is that the next time you update the mirror from the source, you have to be careful to keep that template around, and to keep any other text surrounding the mirrored text. So this may involve some manual merging, and special attention to make sure you only delete the sections you're supposed to delete and not the sections above or below which you actually want to keep...

Solution? A dedicated subpage for each section of mirrored content. This subpage can then be transcluded into the main article / section where it's supposed to appear.

The main advantage of this is that the mirroring process — although still manual, perhaps — can be more brainless and require less attention... That is, you can just copy all of the wikitext from the source page, and then paste all of that in the target page's textarea, replacing anything that's already there.

This can be useful anytime you want to "frame" the mirrored page/content with your own header/footer or to add your own categories to that page.

An example of this: Gems or svn:externals? is the (non-mirrored) "frame" page surrounding the mirrored subpage, Gems or svn:externals? / QualitySmith sync. The frame page is really basic, simply indicating the mirror, transcluding the mirrored page, and adding a custom category:

{{mirror of|http://wiki.qualitysmith.com/Gems_or_svn:externals%3F|:Gems or svn:externals? / QualitySmith sync}}
[[Category:Ruby / Dependencies]]

Argument 2 of Template:Mirror of specifies the subpage that should be transcluded. It will also include a handy edit link, so you can jump straight to the mirrored page from the frame page...

{{include with edit link|:Gems or svn:externals? / QualitySmith sync}}

[edit] Colors in tables

WhyNotWiki / Conventions / Colors in tables edit

[edit] Blocks of example code / Syntax highlighting

MediaWiki / Syntax highlighting edit

<pre class='console'>
> svn propset svn:externals "rails http://dev.rubyonrails.org/svn/rails/trunk" vendor
</pre>

> svn propset svn:externals "rails http://dev.rubyonrails.org/svn/rails/trunk" vendor