Meta:Guidelines: Difference between revisions

(25 intermediate revisions by the same user not shown)

Line 2:

For more general wiki conventions and formatting help , visit the [http://www.mediawiki.org/wiki/Help:Formatting MediaWiki Formatting Guide].

If you're looking for something to contribute to this Wiki, look here for pages that need fixing:

*[[:Category:Pages that need updating]]

*[[:Category:Articles with dead external links]]

==Page Names==

Page names should be descriptive and unique. Use singular nouns instead of plurals when possible (e.g. "Keyboard" instead of "Keyboards"). This makes linking from singular words easier~~, as you can just use~~:

Page names should be descriptive and unique. Use singular nouns instead of plurals when possible (e.g. "Keyboard" instead of "Keyboards"). This makes linking from singular words easier:

<code><nowiki>One [[Keyboard]], Two [[Keyboard]]s.</nowiki></code>

One [[Keyboard]], Two [[~~Keyboard~~]]s.

✅<code><nowiki>One [[Keyboard]], Two [[Keyboard]]s.</nowiki></code>

~~instead of~~

❌<code><nowiki>One [[Keyboards|Keyboard]], Two [[Keyboards]].</nowiki></code>

~~<code><nowiki>~~One [[~~Keyboards|~~Keyboard]], Two [[~~Keyboards~~]].</~~nowiki~~></~~code~~>

Both result in: One [[Keyboard]], Two [[Keyboard]]s.

==Sections==

Always try to group and categorize your information in a logical and user-friendly way. Prevent redundancies: only create subsections if there are more of them at the same level (levels are indicated by number of = signs before and after the section header), otherwise just collapse to the parent.

For some reason, Erik seems to always start at level 2 ('=='). It makes the jump in font-size between the header and text a bit less jarring, but it's mainly done out of a force of habit. Help him break this spell by properly starting your sections at level 1.

You can add many levels of subsections as you like, but after level 3 they become quite hard to distinguish and will clutter the TOC. If a subject requires many sub-subcategories, consider giving the subcategory its own page. Alternatively, if the sub-subcategories are only small in content, you could make non-TOC headers with simple '''bold text'''.

==Links==

Links should be '''descriptive''', and inform the user of where or what the link is directing them to.

'''Dos'''

:✅ Check [https://www.ru.nl/en/departments/faculty-of-social-sciences/technical-support-group-tsg our official website].

:✅ [[Meta:Guidelines#Links|How to format links]]

:⚠️ It can be ok to use full URLs if they're short and/or clear, like https://ru.nl/

'''Donts'''

:❌ Click [https://ru.nl here] for more info.

:❌ Visit https://www.ru.nl/en/departments/faculty-of-social-sciences/technical-support-group-tsg

===Download Links===

You can use a custom template for download links. This adds a little icon in front of it so users can see the link leads to a raw file or direct download. This is to prevent people accidentally downloading things they didn't intend to.

<pre>{{Download link|media=Placeholder.png|Placeholder image|png}}</pre>

===Familiar Sites===

This Wiki has custom templates for linking to commonly used resources that are (more or less) under our control. It helps users identify where external links are going, and know it is safe to click on.

====Gitlab====

<pre>{{Gitlab|tsg/Labcomputer|Lab computer scripts}}</pre>

====Surfdrive====

<pre>{{Surfdrive|b8Rp29u8MGhjb1v|LSL LabRecorder (zip)}}</pre>

~~==Categories==~~

ℹ️ If you want to upload files to the Surfdrive to share on this Wiki, TSG members should place them in the folder "TSG Wiki Resources". This folder should be visible and accessible for all TSG and lab support members. If not, please contact [[Erik van den Berge]].

~~Always try~~ to ~~group~~ and ~~categorize your information~~ in ~~a logical and user-friendly way~~. ~~Prevent redundancies: only create subcategories if there are more of them at~~ the ~~same level (levels are indicated by number of = signs before and~~ after the ~~header), otherwise just collapse to the parent~~.

===Dead links===

If you encounter an external link that no longer works, e.g. if you get a 404 error message or the whole website doesn't exist anymore:

# Try to find where the intended content has moved to and replace the link url.

# Check the page history to see who may've created the link in the first place; ask them to fix it.

# Add the <code><nowiki>{{Dead link}}</nowiki></code> tag after the link. {{Dead link}}

~~You can add many levels of subheaders as you like, but after level 3 they become quite hard to distinguish and~~ will clutter the TOC. If a subject requires many sub-subcategories, consider giving the subcategory its own page. Alternatively, if the sub-subcategories are only small in content, you could make non-TOC headers with ~~simple '''bold text'''~~.

Pages with dead links will automatically show up on [[:Category:Articles with dead external links]].

==Images==

Line 43:

Line 95:

! width="200px" | Item 3

|-

! ~~Category~~

| Regular Info || Info 1 || Info 2 || Info 3

|-

! Comparison

! colspan="3" |

|-

| ~~Colors~~

| Template || <center><code><nowiki>{{Yes}}</nowiki></code></center> || <center><code><nowiki>{{No}}</nowiki></code></center> || <center><code><nowiki>{{Some}}</nowiki></code></center>

| ~~style="background-color:#9F9;"~~ | Yes

| ~~style="background-color:#F99;"~~ | No

| ~~style="background-color:#FFB;"~~ | ~~Wildcard~~

|-

| ~~CSS Code~~ || #9F9|| #F99|| #~~FFB~~

| Result || {{Yes}} || {{No}} || {{Some}}

|-

! colspan="4" |

|-

| Custom name || <center><code><nowiki>{{Yes|Yeah!}}</nowiki></code></center> || <center><code><nowiki>{{No|Nuh-uh}}</nowiki></code></center> || <center><code><nowiki>{{Some|Maybe?}}</nowiki></code></center>

|-

| Result || {{Yes|Yeah!}} || {{No|Nuh-uh}} || {{Some|Maybe?}}

|-

! colspan="4" |

|-

| Manual colors

| style="background-color:#9F9;" | #9F9

| style="background-color:#F99;" | #F99

| style="background-color:#FFD;" | #FFD

|-

|}

==Code==

Line 80:

Line 143:

Prow scuttle parrel provost Sail ho shrouds spirits boom mizzenmast yardarm. Pinnace holystone mizzenmast quarter crow's nest nipperkin grog yardarm hempen halter furl. Swab barque interloper chantey doubloon starboard grog black jack gangway rutters.

Deadlights jack lad schooner scallywag dance the hempen jig carouser broadside cable strike colors. Bring a spring upon her cable holystone blow the man down spanker Shiver me timbers to go on account lookout wherry doubloon chase. Belay yo-ho-ho keelhaul squiffy black spot yardarm spyglass sheet transom heave to.

Sail ho Corsair red ensign hulk smartly boom jib rum gangway. Case shot Shiver me timbers gangplank crack Jennys tea cup ballast Blimey lee snow crow's nest rutters. Fluke jib scourge of the seven seas boatswain schooner gaff booty Jack Tar transom spirits.

Line 100:

Line 161:

====Examples====

ℹ️ This is a piece of (extra) information.

:ℹ️ This is a piece of (extra) information.

:⚠️ This is a warning!

⚠️ This is a warning!

:❌ This is a no-go!

:✅ This is good.

❌ This is a no-go!

:✨ This is something new!

:🚧 This is under construction.

✅ This is good.

:🐽 Oink.

✨ This is something new!

🚧 This is under construction.

🐽 Oink.

These are just examples; feel free to come up with your own conventions so we can later compare and discuss what works best.

==Shields and Badges==

Github-style shields or badges are useful for providing software details like programming language and licensing at a glance. There's a case to be made for our Wiki and Gitlab READMEs to use similar layouts and features for more uniformity in our documentation, and so badges could help with that too. Unfortunately, it is currently a bit of a faff to implement badges on our wiki, as hotlinking dynamic content from external sources is disabled for security reasons.

Github-style shields or badges are useful for providing software details like programming language and licensing at a glance. There's a case to be made for our Wiki and Gitlab READMEs to use similar layouts and features for more uniformity in our documentation, and so badges could help with that too. Unfortunately, it is currently a bit of a faff to implement badges on our wiki, as hotlinking or injecting dynamic content from external sources is disabled for security reasons.

The workaround:

# Generate a badge at https://shields.io

# Create a new CSS rule in [[MediaWiki:Common.css]] (see examples ~~at bottom~~)

# Create a new CSS rule in [[MediaWiki:Common.css]] (see examples below)

# On the page you want to edit, add a custom span with class="shield" and the id as named in the CSS, e.g.: <code><nowiki></nowiki></code>

# Add to the list of shields below.

Line 127:

Line 183:

: <code><nowiki></nowiki></code>

==~~Downloads~~==

==Banners==

~~Download links are presented as list items and are~~ '''~~descriptive~~'''~~. This means you don~~'~~t waste space by pasting the entire url or writing something like "Click [[Meta:Guidelines~~|~~here]] to download the documentation". Examples:~~

If a page is, or needs to be, significantly changed, you can put a banner on top to warn/inform visitors.

*[[:File:Obs_tut_videoSet.png|Uploaded file with version control]]

<pre>{{Notice|Did you know you could add banners?}}</pre>

*[[Media:BITSI_tempalte2015_duemilanove.zip|~~Directly downloadable file]] (zip)~~

<pre>{{Outdated}}</pre>

<pre>{{Under construction}}</pre>

==References==

@@ Line 2: / Line 2: @@
 For more general wiki conventions and formatting help , visit the [http://www.mediawiki.org/wiki/Help:Formatting MediaWiki Formatting Guide].
+If you're looking for something to contribute to this Wiki, look here for pages that need fixing:
+*[[:Category:Pages that need updating]]
+*[[:Category:Articles with dead external links]]
 ==Page Names==
-Page names should be descriptive and unique. Use singular nouns instead of plurals when possible (e.g. "Keyboard" instead of "Keyboards"). This makes linking from singular words easier, as you can just use:<br/>
+Page names should be descriptive and unique. Use singular nouns instead of plurals when possible (e.g. "Keyboard" instead of "Keyboards"). This makes linking from singular words easier:<br/>
-<code><nowiki>One [[Keyboard]], Two [[Keyboard]]s.</nowiki></code><br/>
-One [[Keyboard]], Two [[Keyboard]]s.<br/>
+✅<code><nowiki>One [[Keyboard]], Two [[Keyboard]]s.</nowiki></code><br/>
-instead of<br/>
+❌<code><nowiki>One [[Keyboards|Keyboard]], Two [[Keyboards]].</nowiki></code>
-<code><nowiki>One [[Keyboards|Keyboard]], Two [[Keyboards]].</nowiki></code>
+Both result in: One [[Keyboard]], Two [[Keyboard]]s.
+==Sections==
+Always try to group and categorize your information in a logical and user-friendly way. Prevent redundancies: only create subsections if there are more of them at the same level (levels are indicated by number of = signs before and after the section header), otherwise just collapse to the parent.
+For some reason, Erik seems to always start at level 2 ('=='). It makes the jump in font-size between the header and text a bit less jarring, but it's mainly done out of a force of habit. Help him break this spell by properly starting your sections at level 1.
+You can add many levels of subsections as you like, but after level 3 they become quite hard to distinguish and will clutter the TOC. If a subject requires many sub-subcategories, consider giving the subcategory its own page. Alternatively, if the sub-subcategories are only small in content, you could make non-TOC headers with simple '''bold text'''.
+==Links==
+Links should be '''descriptive''', and inform the user of where or what the link is directing them to.
+'''Dos'''
+:✅ Check [https://www.ru.nl/en/departments/faculty-of-social-sciences/technical-support-group-tsg our official website].
+:✅ [[Meta:Guidelines#Links|How to format links]]
+:⚠️ It can be ok to use full URLs if they're short and/or clear, like https://ru.nl/
+'''Donts'''
+:❌ Click [https://ru.nl here] for more info.
+:❌ Visit https://www.ru.nl/en/departments/faculty-of-social-sciences/technical-support-group-tsg
+===Download Links===
+{{See also|Template:Download link}}
+You can use a custom template for download links. This adds a little icon in front of it so users can see the link leads to a raw file or direct download. This is to prevent people accidentally downloading things they didn't intend to.
+{{Download link|media=Placeholder.png|Placeholder image|png}}
+<pre>{{Download link|media=Placeholder.png|Placeholder image|png}}</pre>
+===Familiar Sites===
+This Wiki has custom templates for linking to commonly used resources that are (more or less) under our control. It helps users identify where external links are going, and know it is safe to click on.
+====Gitlab====
+{{See also|Template:Gitlab}}
+{{Gitlab|tsg/Labcomputer|Lab computer scripts}}
+<pre>{{Gitlab|tsg/Labcomputer|Lab computer scripts}}</pre>
+====Surfdrive====
+{{See also|Template:Surfdrive}}
+{{Surfdrive|b8Rp29u8MGhjb1v|LSL LabRecorder (zip)}}
+<pre>{{Surfdrive|b8Rp29u8MGhjb1v|LSL LabRecorder (zip)}}</pre>
-==Categories==
+ℹ️ If you want to upload files to the Surfdrive to share on this Wiki, TSG members should place them in the folder "TSG Wiki Resources". This folder should be visible and accessible for all TSG and lab support members. If not, please contact [[Erik van den Berge]].
-Always try to group and categorize your information in a logical and user-friendly way. Prevent redundancies: only create subcategories if there are more of them at the same level (levels are indicated by number of = signs before and after the header), otherwise just collapse to the parent.
+===Dead links===
+If you encounter an external link that no longer works, e.g. if you get a 404 error message or the whole website doesn't exist anymore:
+# Try to find where the intended content has moved to and replace the link url.
+# Check the page history to see who may've created the link in the first place; ask them to fix it.
+# Add the <code><nowiki>{{Dead link}}</nowiki></code> tag after the link. {{Dead link}}
-You can add many levels of subheaders as you like, but after level 3 they become quite hard to distinguish and will clutter the TOC. If a subject requires many sub-subcategories, consider giving the subcategory its own page. Alternatively, if the sub-subcategories are only small in content, you could make non-TOC headers with simple '''bold text'''.
+Pages with dead links will automatically show up on [[:Category:Articles with dead external links]].
 ==Images==
@@ Line 43: / Line 95: @@
 ! width="200px" | Item 3
 |-
-! Category
+| Regular Info || Info 1 || Info 2 || Info 3
+|-
+! Comparison
 ! colspan="3" |
 |-
-| Colors
+| Template || <center><code><nowiki>{{Yes}}</nowiki></code></center> || <center><code><nowiki>{{No}}</nowiki></code></center> || <center><code><nowiki>{{Some}}</nowiki></code></center>
-| style="background-color:#9F9;" | Yes
-| style="background-color:#F99;" | No
-| style="background-color:#FFB;" | Wildcard
 |-
-| CSS Code || #9F9|| #F99|| #FFB
+| Result || {{Yes}} || {{No}} || {{Some}}
+|-
+! colspan="4" |
+|-
+| Custom name || <center><code><nowiki>{{Yes|Yeah!}}</nowiki></code></center>  || <center><code><nowiki>{{No|Nuh-uh}}</nowiki></code></center>  || <center><code><nowiki>{{Some|Maybe?}}</nowiki></code></center>
+|-
+| Result || {{Yes|Yeah!}} || {{No|Nuh-uh}} || {{Some|Maybe?}}
+|-
+! colspan="4" |
+|-
+| Manual colors
+| style="background-color:#9F9;" | #9F9
+| style="background-color:#F99;" | #F99
+| style="background-color:#FFD;" | #FFD
 |-
 |}
 ==Code==
@@ Line 80: / Line 143: @@
 <!-- Start Pirate Ipsum-->
 Prow scuttle parrel provost Sail ho shrouds spirits boom mizzenmast yardarm. Pinnace holystone mizzenmast quarter crow's nest nipperkin grog yardarm hempen halter furl. Swab barque interloper chantey doubloon starboard grog black jack gangway rutters.
 Deadlights jack lad schooner scallywag dance the hempen jig carouser broadside cable strike colors. Bring a spring upon her cable holystone blow the man down spanker Shiver me timbers to go on account lookout wherry doubloon chase. Belay yo-ho-ho keelhaul squiffy black spot yardarm spyglass sheet transom heave to.
 Sail ho Corsair red ensign hulk smartly boom jib rum gangway. Case shot Shiver me timbers gangplank crack Jennys tea cup ballast Blimey lee snow crow's nest rutters. Fluke jib scourge of the seven seas boatswain schooner gaff booty Jack Tar transom spirits.
 <!-- End Pirate Ipsum-->
@@ Line 100: / Line 161: @@
 ====Examples====
-ℹ️ This is a piece of (extra) information.
+:ℹ️ This is a piece of (extra) information.
+:⚠️ This is a warning!
-⚠️ This is a warning!
+:❌ This is a no-go!
+:✅ This is good.
-❌ This is a no-go!
+:✨ This is something new!
+:🚧 This is under construction.
-✅ This is good.
+:🐽 Oink.
-✨ This is something new!
-🚧 This is under construction.
-🐽 Oink.
 These are just examples; feel free to come up with your own conventions so we can later compare and discuss what works best.
 ==Shields and Badges==
-Github-style shields or badges are useful for providing software details like programming language and licensing at a glance. There's a case to be made for our Wiki and Gitlab READMEs to use similar layouts and features for more uniformity in our documentation, and so badges could help with that too. Unfortunately, it is currently a bit of a faff to implement badges on our wiki, as hotlinking dynamic content from external sources is disabled for security reasons.
+Github-style shields or badges are useful for providing software details like programming language and licensing at a glance. There's a case to be made for our Wiki and Gitlab READMEs to use similar layouts and features for more uniformity in our documentation, and so badges could help with that too. Unfortunately, it is currently a bit of a faff to implement badges on our wiki, as hotlinking or injecting dynamic content from external sources is disabled for security reasons.
 The workaround:
 # Generate a badge at https://shields.io
-# Create a new CSS rule in [[MediaWiki:Common.css]] (see examples at bottom)
+# Create a new CSS rule in [[MediaWiki:Common.css]] (see examples below)
 # On the page you want to edit, add a custom span with class="shield" and the id as named in the CSS, e.g.: <code><nowiki><span class="shield" id="shield-python310")></span></nowiki></code>
 # Add to the list of shields below.
@@ Line 127: / Line 183: @@
 :<span class="shield" id="shield-python310")></span> <code><nowiki><span class="shield" id="shield-python310")></span></nowiki></code>
-==Downloads==
+==Banners==
-Download links are presented as list items and are '''descriptive'''. This means you don't waste space by pasting the entire url or writing something like "Click [[Meta:Guidelines|here]] to download the documentation". Examples:
+If a page is, or needs to be, significantly changed, you can put a banner on top to warn/inform visitors.
-*[[:File:Obs_tut_videoSet.png|Uploaded file with version control]]
+<pre>{{Notice|Did you know you could add banners?}}</pre>
-*[[Media:BITSI_tempalte2015_duemilanove.zip|Directly downloadable file]] (zip)
+{{Notice|Did you know you could add banners?}}
+<pre>{{Warn|'''Look Out!'''}}</pre>
+{{Warn|'''Look Out!'''}}
+<pre>{{Outdated}}</pre>
+{{Outdated|nocat=true}}
+<pre>{{Under construction}}</pre>
+{{Under construction|nocat=true}}
 ==References==
 <references />

Meta:Guidelines: Difference between revisions

Navigation menu

Search