Difference between revisions of "Meta:Guidelines"

From TSG Doc
Jump to: navigation, search
(Code)
 
Line 91: Line 91:
  
 
==Downloads==
 
==Downloads==
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 [[Main_Page|here]] to download the documentation". Examples:
+
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:
 
*[[:File:riv2 quickstart.pdf|Uploaded file with version control]]
 
*[[:File:riv2 quickstart.pdf|Uploaded file with version control]]
 
*[[Media:BITSI_tempalte2015_duemilanove.zip|Directly downloadable file]] (zip)
 
*[[Media:BITSI_tempalte2015_duemilanove.zip|Directly downloadable file]] (zip)

Latest revision as of 16:11, 31 March 2017

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.


Categories

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.

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.

Images

Right-floating image thumbnail with description.

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. 300px is the preferred thumbnail size. Adding a description underneath the image is appreciated. For more image formatting guidelines, visit the MediaWiki Images Guide.

Inline Images

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. The exact size is up to you, but the width should not exceed 720px.[1]

Caption

You can prevent text that is placed after the image from flowing next to the image by placing an HTML break behind it.

Tables

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
Category
Colors Yes No Wildcard
CSS Code #9F9 #F99 #FFB


Code

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.
Supports syntax highlighting of certain languages, like Python and HTML.
Change the lang="" attribute to the correct language, e.g. lang="python" or lang="html5"
Use lang="text" for non-supported languages.


 1 You can also add line numbering.
 2 
 3 If your code is longer than, say, 50 lines, you can add a style attribute to introduce a scrollbar, as sampled here. For a 50-line cutoff, use style="height:50em; overflow:auto;".
 4 Note that this method will cause the print version of the page to cut off the code at the line limit mark and not print the rest of the code.
 5 I might fix that, but if it's really crucial to have an entire page full of code, you should probably give it a separate page.
 6 
 7 <!-- Commence Bacon Ipsum -->
 8 Bacon ipsum dolor amet eiusmod in ribeye, flank duis swine drumstick shank kielbasa lorem pariatur shoulder in. Flank capicola dolore, tri-tip boudin fatback turkey. 
 9 Ut esse in voluptate porchetta duis reprehenderit irure ullamco mollit tri-tip bresaola. Anim beef bresaola meatball t-bone spare ribs consequat ullamco. 
10 Shoulder sirloin fatback veniam dolore. Adipisicing sed tempor shank lorem, pariatur tri-tip et pork loin tail chuck meatloaf.
11 
12 Exercitation beef ribs short loin veniam pig, incididunt spare ribs. In ipsum biltong ex enim, boudin chuck andouille velit duis cow prosciutto elit. 
13 Duis tongue laborum veniam do meatloaf porchetta boudin minim aute in meatball ex turkey occaecat. Dolor kevin officia shoulder corned beef.
14 
15 Pork irure non, et nulla qui prosciutto boudin. Pancetta in turducken magna doner do dolor anim ad meatball prosciutto. Officia excepteur drumstick kielbasa ullamco, 
16 velit qui capicola aliquip. Cillum commodo nulla elit drumstick kevin turducken ut consectetur. Frankfurter in in boudin jerky. Do in anim ut sunt voluptate bresaola sed. 
17 Est leberkas nulla, incididunt biltong bacon boudin rump dolore dolore kielbasa proident kevin aliqua.

For command-line code, you can also style it like this for clarity: ping 127.0.0.1 -n 50 -l 1024

You could also use the <tt> <pre> and nowiki tags if better suited for your needs, whatever works best to present the code as clear and readable as possible.

Downloads

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:

References

  1. Thumbnails 720px wide still fit comfortably within a browser window on half a 1920px desktop monitor.