Difference between revisions of "Meta:Guidelines"
(Created page with "This is a sample page for the tsgdoc Wiki and can be used as reference for creating new pages. Note that this introduction is conventionally placed above the Table Of Contents...")
m (E.vandenberge moved page Meta:Sample to Meta:Guidelines without leaving a redirect: Name change to fit purpose)
Revision as of 11:15, 30 April 2015
This is a sample page for the tsgdoc Wiki and can be used as reference for creating new pages. Note that this introduction is conventionally placed above the Table Of Contents (TOC), so visitors can immediately see what this page is about, instead of having to scroll passed the TOC.
For more general wiki conventions and formatting help , visit the MediaWiki Formatting Guide.
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.
Visitors typically use one of two methods to find the information they need: Hunting and Gathering. There is probably a more official set of terms for these methods, but let's role with this analogy for now.
The "Hunter" will look for specific information on a page based on specific keywords. Make your headers sufficiently descriptive, so the user can jump directly to the required information using the Table Of Contents.
The "Gatherer" doesn't know exactly what to look for, and will browse the entire page before figuring out what information they need based on the context it is presented in. You can guide these visitors in a helpful way by sorting your content in order of specificity; from general or most used information at the top, to specific or least used information (e.g. software code) at the bottom.
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.
To optimize screen space, images should be placed in a floating window, aligned to the right side of the screen. Larger images can be automatically resized to thumbnails, by specifying the thumbnail width. 200px is the preferred thumbnail size. Adding a description underneath the image is appreciated. For more image formatting guidelines, visit the MediaWiki Images Guide.
Images that are used, for instance, as part of a step-by-step tutorial can be placed inline, with larger size to make them more readable.
You can prevent text that is placed after the image from flowing next to the image by placing an HTML break behind it.
For tables, use the Wikitable markup. It is more readable and easy on the eye than the default one. There are multiple ways to create rows and columns, some used in the example below, but for more information, consult the MediaWiki Table Formatting Guide.
By default, table columns will scale to fit the contents of the cell, but this usually results in a messy-looking table. Set fixed column-widths to keep the table nice and tight.
For binary entries (e.g. Yes/No), a background color can be used to make it easier to recognize.
|Item 1||Item 2||Item 3|
If you want to add code, the syntax might interfere with the Mediawiki syntax. To prevent this from happening, place your code in one of the following preferred ways:
Fixed format text for short, single-line code.
Long code, spans entire width of the page <!-- start slipsum code --> Well, the way they make shows is, they make one show. That show's called a pilot. Then they show that show to the people who make shows, and on the strength of that one show they decide if they're going to make more shows. Some pilots get picked and become television programs. Some don't, become nothing. She starred in one of the ones that became nothing. Like you, I used to think the world was this great place where everybody lived by the same standards I did, then some kid with a nail showed me I was living in his world, a world where chaos rules not order, a world where righteousness is not rewarded. That's Cesar's world, and if you're not willing to play by his rules, then you're gonna have to pay the price. Now that we know who you are, I know who I am. I'm not a mistake! It all makes sense! In a comic, you know how you can tell who the arch-villain's going to be? He's the exact opposite of the hero. And most times they're friends, like you and me! I should've known way back when... You know why, David? Because of the kids. They called me Mr Glass.
You could also use the <code> and nowiki tags, but they are displayed in different ways depending on the content, so use with care.
Any information that you want to present as a download link should be placed under this header. This includes manuals, drivers, software installs, etc. Sub-categorize where needed. 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 here to download the documentation". Examples:
Conventionally, download links are found on the bottom of a Wiki page, but considering the frequency at which they are accessed from this particular Wiki, they can be placed earlier as well.