767
edits
Changes
Jump to navigation
Jump to search
Stanford SSI Wiki:How to Write an Article (view source)
Revision as of 03:34, 30 December 2015
, 03:34, 30 December 2015Created page with "Hello! Thank you for joining the SSI Wiki! This article talks about the wiki, why it's important, and how you can help by contributing to it. == The Wiki and Why it Matters =..."
Hello! Thank you for joining the SSI Wiki! This article talks about the wiki, why it's important, and how you can help by contributing to it.
== The Wiki and Why it Matters ==
The SSI Wiki is intended as an publicly visible base for knowledge accumulated by SSI members about SSI, including project histories, design decisions, understandings of relevant concepts, information about relevant people, and more. This helps preserve [https://en.wikipedia.org/wiki/Institutional_memory institutional memory], while also allowing SSI to share its work with other university space groups and the world as a whole. Using the wiki to document projects is also important as a means of demonstrating SSI's continued commitment to Stanford's Openness in Research policy and to the inclusion of international students by satisfying the public disclosure requirements of Fundamental Research as defined by US Export Control regulations.
== What Belongs in the Wiki ==
As described above, the following things should be included in the SSI Wiki:
; SSI Members and Other Relevant SSI-Involved People
: Individual members should write a small note about themselves on their User page (for example, [[User:Ehillstrom]]). [[:Category: Faculty Advisors | Faculty Advisors]] also have wiki pages.
; SSI Teams
: Descriptions of past and current work by SSI Teams belongs on their team page (for example, the [[Optical Communications Team]]).
; SSI Projects and Equipment
: Projects SSI is undertaking and noteworthy items built in the course of undertaking them typically deserve their own pages (for example, each [[:Category:Balloon Launches | launched balloon]] has a page).
; Specific Relevant Technical Articles
: The intent of this wiki is not to duplicate Wikipedia. Many technical concepts of use to SSI are very well documented on Wikipedia (and updated by a much larger community), and so whenever it is necessary to link to a concept in an article it is best to first check Wikipedia to see if there is a relevant article there. Articles for technical concepts should be created when:
:* No good, single Wikipedia article exists (ie. [[Optical Internet Backhaul]])
:* The Wikipedia article is esoteric or poorly explains the concept for how SSI interacts with it (ie. [[Signal-to-Noise Ratio]])
:* The concept is novel, created by SSI (ie. [[Valve-Ballast Altitude Control]])
:* Documenting a project from an outside group, where documentation may exist but not in an easy-to-find form (ie. [[FitSat-1]])
== How to Create or Edit a Page ==
[[File:CreateAnArticle.png|400px|right|thumb|Image of search results for a nonexistent page (at the time), showing the red link to create said page]]
Before creating a page, it is strongly recommended that you create an account, by clicking the "Create Account" button in the upper right of any page and following the dialogue. '''Please choose a username that clearly corresponds with your real name.''' Good username examples include [[User:Iangomez]] and [[User:Amilich]], while a less good example is [[User:Elongnation]].
Next, search the title of the article you're looking to create. If it or a similar page already exists, that's a good indication you needn't create a new page. Otherwise, create the page by clicking the relevant link (see right).
To edit a page, simply click the "Edit" button in the upper right hand corner of the page. Most pages are editable by all members; pages that are prone to vandalism may become protected, imposing restrictions on which users can edit them. Edits should be made to pages whenever you see information that is inaccurate or whenever you feel the content or its presentation (i.e. phrasing, spelling, grammar) can be improved.
Creating or editing a page will bring up an in-browser text editor, where you can type in the article content or edit existing content. Formatting of article content is described below.
== Article Formatting ==
The SSI Wiki is powered by MediaWiki, the backbone of Wikipedia and many other online wikis. '''MediaWiki replaces normal HTML,''' applying a large body of formatting to ''mostly'' plain text. All wiki pages are stored as this mostly plain text, and MediaWiki formats them when they are rendered in a browser. Wiki pages thus need to be written using MediaWiki's formatting rules. MediaWiki's features are extensive and the subject of their own [https://www.mediawiki.org/wiki/MediaWiki wiki], which is an incredibly detailed reference for advanced formatting and formatting questions. The basic elements of MediaWiki formatting are described below; search the MediaWiki wiki for more information.
=== Paragraphs ===
Mediawiki automatically creates paragraphs out of separate blocks of text. A blank line separating two sections of text will cause them to appear as separate paragraphs. Putting more than one line between two paragraphs will increase the spacing between them.
=== Boldface and Italics ===
Text surrounded by three quotation marks on either side will appear in '''bold''' (<code><nowiki>'''bold'''</nowiki></code>).
Text surrounded by two quotation marks on either side will appear in ''italics'' (<code><nowiki>''italics''</nowiki></code>).
=== Headings ===
Headings are a good way of dividing and subdividing an article, as they automatically create an outline at the top of the page.
*To create a section heading (formatted like "[[#Article Formatting|Article Formatting]]" above) surround the heading with two equals signs on either side (<code><nowiki>== Section Heading ==</nowiki></code>).
*To create a subsection heading (formatted like "[[#Headings|Headings]]" above) surround the subheading with three equals signs on either side (<code><nowiki>=== Subection Heading ===</nowiki></code>).
*To create a ''sub''subsection heading surround the subsubheading with ''four'' equals signs on either side (<code><nowiki>==== Subsubection Heading ====</nowiki></code>).
MediaWiki also supports page level headings (<code><nowiki>= Page Heading =</nowiki></code>) which should not be used, and several additional, smaller headings (with more equals signs on either side) which can be used.
=== Categories ===
To aid in finding pages, it helps to tag pages as members of relevant categories. For example, every team has a category for all articles pertinent to their work. Links to their category pages are located in the wiki's left-hand sidebar.
To tag a page as a member of a category (which will cause it to be automatically listed on that category page), add <code><nowiki>[[Category:Category Name]]</nowiki></code> at the bottom of the article.
=== Links ===
'''Standard hyperlinks do not work in MediaWiki pages.''' Link formatting is dependent on what content is being linked to.
*To create a link to a page within the SSI Wiki, simply surround the page title ('''not''' the URL) with two square brackets on either side (<code><nowiki>[[Page Title]]</nowiki></code>).
*To create a link to a wiki page ''while displaying text other than the page title,'' add a "pipe" character ("|") and then the text to display (<code><nowiki>[[Page Title | real text]]</nowiki></code>).
*To create a link to a heading on a wiki page, use a "pound" sign ("#") and then the heading after the page title (<code><nowiki>[[Page Title#Heading]]</nowiki></code>, or <code><nowiki>[[#Heading]]</nowiki></code> for a heading on the same page as the link). These links can also have alternate displayed text (<code><nowiki>[[Page Title#Heading | real text]]</nowiki></code>).
*To link to a category, without sorting the page into that category, add a colon before the category page link (<code><nowiki>[[:Category:Category Name]]</nowiki></code>). These links can also have alternate displayed text (<code><nowiki>[[:Category:Category Name | real text]]</nowiki></code>).
All of the above link styles are ''internal'' links and will appear in red if the page or header being linked to does not exist. It is best practice to test all blue (valid) links to ensure that they do in fact link to the page they are intended to link to.
To link to an external URL, place '''single''' square brackets around the full URL (including <nowiki>"http://"</nowiki>) followed by a space and the link text that should be displayed (<code><nowiki>[http://ssi.stanford.edu SSI Website Link]</nowiki></code>).
=== Templates ===
Templates are an important feature of MediaWiki that allow preformatted sections to be automatically populated on different pages. The actual design of templates is somewhat complicated, and is described in [[SSI Wiki:How to Create a Template]]. A list of currently available templates is maintained at [[:Category:Templates]].
The syntax for including a template in a page is <code><nowiki>{{template-name}}</nowiki></code>. Templates may also have parameters that change what content is displayed (for example, [[Template:Balloon-launch]]). For these, the syntax is <code><nowiki>{{template-name | parameter1 = value1 | parameter2 = value2}}</nowiki></code>. Templates typically have usage instructions on their page in [[:Category:Templates]], and they are designed to have self-documenting names and parameters. You can look at examples of a template in use (in the sidebar on the left side; under "Tools," click "What links here") to help learn how to use it. Looking at a template page's edit history (in the page's upper right) to see who created it and asking them questions may also prove helpful.
==== Stubs ====
{{balloon-stub}}
One special type of template is the ''stub'' templates, an example of which is shown above. A relevant stub template should be placed on any page that needs to be expanded - there are specific stubs for various topics, including one for each team.
=== Redirects ===
If a search term other than an article's full title is likely to be used, it's helpful to create a redirect to connect that search term to the article. A redirect is a new page (titled with the desired search term) containing one line as follows:
<nowiki>
#REDIRECT [[Article to be redirected to]]
</nowiki>
== Editing Guidelines ==
When creating or editing a page, practice the following:
*'''Do not be afraid to create and edit pages.''' Every bit of information added, every inaccuracy corrected, and every bit of formatting fixed makes for a better wiki. To this end, eliminating red links (either by fixing them or creating the pages they point to), marking stubs, adding content to stubs, creating and fixing redirects, and generally being a good wiki citizen is asked of every user. If we all do our part, this site will continually become a better resource for SSI and the worldwide space community.
*'''Add an edit summary following every single page edit.''' This helps others know what you changed - even if the change is small, it is important to make a note saying so. When creating a page, you are not required to make a summary - the page's creation is self-evident.
*'''Make edits while logged in to your account.''' Edits made merely from an IP address cannot be attributed to a person, which is bad for a variety of reasons.
*'''Use the "Show preview" button in the editor liberally''' - it helps you confirm that your formatting is correct. You should definitely preview every page at least once before saving, to make sure there are no glaring errors.
*'''Check the "Minor edit" box when correcting small spelling and grammar mistakes.''' Changes to content are typically not considered minor edits.
*'''Use templates whenever possible.''' If you're creating content that would be useful on a number of different pages or formatting a section on several different pages similarly, you should be using a template (which may mean [[SSI Wiki:How to Create a Template | creating your own]]).
*'''Use title case for article titles,''' capitalizing the first, the last, and all significant words in the title. Be aware that this differs from Wikipedia article title capitalization, where only the first word and proper nouns are capitalized.
*'''Add external links when possible,''' but understand that unlike Wikipedia, much of the SSI wiki content is original work and as such is not encyclopedic.
== Satire and Tone ==
[[:Category:Satire | Satire]] is a welcome part of the SSI Wiki, as it makes the wiki often much more entertaining to read (and write) and encourages people to explore the site. Pages containing meaningful technical information, however, should be serious, with satirical content confined to satire pages, which must be tagged as part of [[:Category: Satire]]. '''Relevant''' linking to satirical pages from serious ones (and vice versa) is strongly encouraged. ''All this being said, the principal function of the SSI Wiki is to document technical information, and the excessive creation of satirical pages will lead to pages being deleted and people being sad.''
== The Wiki and Why it Matters ==
The SSI Wiki is intended as an publicly visible base for knowledge accumulated by SSI members about SSI, including project histories, design decisions, understandings of relevant concepts, information about relevant people, and more. This helps preserve [https://en.wikipedia.org/wiki/Institutional_memory institutional memory], while also allowing SSI to share its work with other university space groups and the world as a whole. Using the wiki to document projects is also important as a means of demonstrating SSI's continued commitment to Stanford's Openness in Research policy and to the inclusion of international students by satisfying the public disclosure requirements of Fundamental Research as defined by US Export Control regulations.
== What Belongs in the Wiki ==
As described above, the following things should be included in the SSI Wiki:
; SSI Members and Other Relevant SSI-Involved People
: Individual members should write a small note about themselves on their User page (for example, [[User:Ehillstrom]]). [[:Category: Faculty Advisors | Faculty Advisors]] also have wiki pages.
; SSI Teams
: Descriptions of past and current work by SSI Teams belongs on their team page (for example, the [[Optical Communications Team]]).
; SSI Projects and Equipment
: Projects SSI is undertaking and noteworthy items built in the course of undertaking them typically deserve their own pages (for example, each [[:Category:Balloon Launches | launched balloon]] has a page).
; Specific Relevant Technical Articles
: The intent of this wiki is not to duplicate Wikipedia. Many technical concepts of use to SSI are very well documented on Wikipedia (and updated by a much larger community), and so whenever it is necessary to link to a concept in an article it is best to first check Wikipedia to see if there is a relevant article there. Articles for technical concepts should be created when:
:* No good, single Wikipedia article exists (ie. [[Optical Internet Backhaul]])
:* The Wikipedia article is esoteric or poorly explains the concept for how SSI interacts with it (ie. [[Signal-to-Noise Ratio]])
:* The concept is novel, created by SSI (ie. [[Valve-Ballast Altitude Control]])
:* Documenting a project from an outside group, where documentation may exist but not in an easy-to-find form (ie. [[FitSat-1]])
== How to Create or Edit a Page ==
[[File:CreateAnArticle.png|400px|right|thumb|Image of search results for a nonexistent page (at the time), showing the red link to create said page]]
Before creating a page, it is strongly recommended that you create an account, by clicking the "Create Account" button in the upper right of any page and following the dialogue. '''Please choose a username that clearly corresponds with your real name.''' Good username examples include [[User:Iangomez]] and [[User:Amilich]], while a less good example is [[User:Elongnation]].
Next, search the title of the article you're looking to create. If it or a similar page already exists, that's a good indication you needn't create a new page. Otherwise, create the page by clicking the relevant link (see right).
To edit a page, simply click the "Edit" button in the upper right hand corner of the page. Most pages are editable by all members; pages that are prone to vandalism may become protected, imposing restrictions on which users can edit them. Edits should be made to pages whenever you see information that is inaccurate or whenever you feel the content or its presentation (i.e. phrasing, spelling, grammar) can be improved.
Creating or editing a page will bring up an in-browser text editor, where you can type in the article content or edit existing content. Formatting of article content is described below.
== Article Formatting ==
The SSI Wiki is powered by MediaWiki, the backbone of Wikipedia and many other online wikis. '''MediaWiki replaces normal HTML,''' applying a large body of formatting to ''mostly'' plain text. All wiki pages are stored as this mostly plain text, and MediaWiki formats them when they are rendered in a browser. Wiki pages thus need to be written using MediaWiki's formatting rules. MediaWiki's features are extensive and the subject of their own [https://www.mediawiki.org/wiki/MediaWiki wiki], which is an incredibly detailed reference for advanced formatting and formatting questions. The basic elements of MediaWiki formatting are described below; search the MediaWiki wiki for more information.
=== Paragraphs ===
Mediawiki automatically creates paragraphs out of separate blocks of text. A blank line separating two sections of text will cause them to appear as separate paragraphs. Putting more than one line between two paragraphs will increase the spacing between them.
=== Boldface and Italics ===
Text surrounded by three quotation marks on either side will appear in '''bold''' (<code><nowiki>'''bold'''</nowiki></code>).
Text surrounded by two quotation marks on either side will appear in ''italics'' (<code><nowiki>''italics''</nowiki></code>).
=== Headings ===
Headings are a good way of dividing and subdividing an article, as they automatically create an outline at the top of the page.
*To create a section heading (formatted like "[[#Article Formatting|Article Formatting]]" above) surround the heading with two equals signs on either side (<code><nowiki>== Section Heading ==</nowiki></code>).
*To create a subsection heading (formatted like "[[#Headings|Headings]]" above) surround the subheading with three equals signs on either side (<code><nowiki>=== Subection Heading ===</nowiki></code>).
*To create a ''sub''subsection heading surround the subsubheading with ''four'' equals signs on either side (<code><nowiki>==== Subsubection Heading ====</nowiki></code>).
MediaWiki also supports page level headings (<code><nowiki>= Page Heading =</nowiki></code>) which should not be used, and several additional, smaller headings (with more equals signs on either side) which can be used.
=== Categories ===
To aid in finding pages, it helps to tag pages as members of relevant categories. For example, every team has a category for all articles pertinent to their work. Links to their category pages are located in the wiki's left-hand sidebar.
To tag a page as a member of a category (which will cause it to be automatically listed on that category page), add <code><nowiki>[[Category:Category Name]]</nowiki></code> at the bottom of the article.
=== Links ===
'''Standard hyperlinks do not work in MediaWiki pages.''' Link formatting is dependent on what content is being linked to.
*To create a link to a page within the SSI Wiki, simply surround the page title ('''not''' the URL) with two square brackets on either side (<code><nowiki>[[Page Title]]</nowiki></code>).
*To create a link to a wiki page ''while displaying text other than the page title,'' add a "pipe" character ("|") and then the text to display (<code><nowiki>[[Page Title | real text]]</nowiki></code>).
*To create a link to a heading on a wiki page, use a "pound" sign ("#") and then the heading after the page title (<code><nowiki>[[Page Title#Heading]]</nowiki></code>, or <code><nowiki>[[#Heading]]</nowiki></code> for a heading on the same page as the link). These links can also have alternate displayed text (<code><nowiki>[[Page Title#Heading | real text]]</nowiki></code>).
*To link to a category, without sorting the page into that category, add a colon before the category page link (<code><nowiki>[[:Category:Category Name]]</nowiki></code>). These links can also have alternate displayed text (<code><nowiki>[[:Category:Category Name | real text]]</nowiki></code>).
All of the above link styles are ''internal'' links and will appear in red if the page or header being linked to does not exist. It is best practice to test all blue (valid) links to ensure that they do in fact link to the page they are intended to link to.
To link to an external URL, place '''single''' square brackets around the full URL (including <nowiki>"http://"</nowiki>) followed by a space and the link text that should be displayed (<code><nowiki>[http://ssi.stanford.edu SSI Website Link]</nowiki></code>).
=== Templates ===
Templates are an important feature of MediaWiki that allow preformatted sections to be automatically populated on different pages. The actual design of templates is somewhat complicated, and is described in [[SSI Wiki:How to Create a Template]]. A list of currently available templates is maintained at [[:Category:Templates]].
The syntax for including a template in a page is <code><nowiki>{{template-name}}</nowiki></code>. Templates may also have parameters that change what content is displayed (for example, [[Template:Balloon-launch]]). For these, the syntax is <code><nowiki>{{template-name | parameter1 = value1 | parameter2 = value2}}</nowiki></code>. Templates typically have usage instructions on their page in [[:Category:Templates]], and they are designed to have self-documenting names and parameters. You can look at examples of a template in use (in the sidebar on the left side; under "Tools," click "What links here") to help learn how to use it. Looking at a template page's edit history (in the page's upper right) to see who created it and asking them questions may also prove helpful.
==== Stubs ====
{{balloon-stub}}
One special type of template is the ''stub'' templates, an example of which is shown above. A relevant stub template should be placed on any page that needs to be expanded - there are specific stubs for various topics, including one for each team.
=== Redirects ===
If a search term other than an article's full title is likely to be used, it's helpful to create a redirect to connect that search term to the article. A redirect is a new page (titled with the desired search term) containing one line as follows:
<nowiki>
#REDIRECT [[Article to be redirected to]]
</nowiki>
== Editing Guidelines ==
When creating or editing a page, practice the following:
*'''Do not be afraid to create and edit pages.''' Every bit of information added, every inaccuracy corrected, and every bit of formatting fixed makes for a better wiki. To this end, eliminating red links (either by fixing them or creating the pages they point to), marking stubs, adding content to stubs, creating and fixing redirects, and generally being a good wiki citizen is asked of every user. If we all do our part, this site will continually become a better resource for SSI and the worldwide space community.
*'''Add an edit summary following every single page edit.''' This helps others know what you changed - even if the change is small, it is important to make a note saying so. When creating a page, you are not required to make a summary - the page's creation is self-evident.
*'''Make edits while logged in to your account.''' Edits made merely from an IP address cannot be attributed to a person, which is bad for a variety of reasons.
*'''Use the "Show preview" button in the editor liberally''' - it helps you confirm that your formatting is correct. You should definitely preview every page at least once before saving, to make sure there are no glaring errors.
*'''Check the "Minor edit" box when correcting small spelling and grammar mistakes.''' Changes to content are typically not considered minor edits.
*'''Use templates whenever possible.''' If you're creating content that would be useful on a number of different pages or formatting a section on several different pages similarly, you should be using a template (which may mean [[SSI Wiki:How to Create a Template | creating your own]]).
*'''Use title case for article titles,''' capitalizing the first, the last, and all significant words in the title. Be aware that this differs from Wikipedia article title capitalization, where only the first word and proper nouns are capitalized.
*'''Add external links when possible,''' but understand that unlike Wikipedia, much of the SSI wiki content is original work and as such is not encyclopedic.
== Satire and Tone ==
[[:Category:Satire | Satire]] is a welcome part of the SSI Wiki, as it makes the wiki often much more entertaining to read (and write) and encourages people to explore the site. Pages containing meaningful technical information, however, should be serious, with satirical content confined to satire pages, which must be tagged as part of [[:Category: Satire]]. '''Relevant''' linking to satirical pages from serious ones (and vice versa) is strongly encouraged. ''All this being said, the principal function of the SSI Wiki is to document technical information, and the excessive creation of satirical pages will lead to pages being deleted and people being sad.''