Difference between revisions of "Wiki Help"

From FamiLAB Wiki
Jump to: navigation, search
m (Fixes category.)
 
(12 intermediate revisions by 4 users not shown)
Line 1: Line 1:
−
<pre style="font-size:120%; color:green; font-weight:bold; background-color:black;">This section is in progress by @bot.</pre>
 
−
 
 
'''So you want to contribute to the wiki? Welcome!'''
 
'''So you want to contribute to the wiki? Welcome!'''
  
Line 6: Line 4:
  
 
This page includes an overview of Wiki style syntax (all the weird, nonintuitive symbols you have to use to make it readable), as well as tips on writing your content.
 
This page includes an overview of Wiki style syntax (all the weird, nonintuitive symbols you have to use to make it readable), as well as tips on writing your content.
 +
 +
'''TODO''': Sheet of all Wiki pages, last edit date and status.
  
 
__TOC__
 
__TOC__
  
 
==Gathering information==
 
==Gathering information==
 +
 +
The first step to contributing is research.
 +
 +
Define a goal for your user content. It may already be in the title of the page (ex. "How to Turn on the Laser Printer"), or you may need to ask other members what they want to know (ex. something more vague, like "Biohacking". Is the article "What is Biohacking"? Is it "Getting Started with Biohacking"?).
 +
 +
The following is @bot's personal information gathering process:
 +
 +
# '''Figure out what the heck you're writing about.'''
 +
# '''Write questions.''' What would you ask as a user? Is this dangerous? What does that red button do? Save those questions for later.
 +
# '''Contact the expert.''' See if they can set aside time to show you the procedure. Send them your questions and the scope of your article so they can prepare. If you're the lab's resident expert, draft the procedure before you execute it.
 +
# '''Observe the procedure.''' Keep notes to a minimum by recording it (ask permission first, of course). You don't have to share the recording, but it will be helpful to reference while you write the procedure steps. Do the procedure yourself if it helps you learn.
 +
# '''Write!''' This is the fun part. Throw together a draft on the Wiki. It doesn't have to be perfect.
 +
# '''Review.''' Ask the SME (Subject Matter Expert) and another member to review your document. They can check for accuracy ''and'' embarrassing typos.
 +
# '''Test.''' This can be as easy as doing the procedure yourself, following along with your article. Collect user feedback. Edit as needed!
 +
 +
All Wiki contribution helps! Don't be afraid to ask for help finishing a Wiki page if it's outside of your comfort zone. The hardest part is starting, and you've done that just by reading this page.
  
 
==Help article organization==
 
==Help article organization==
Line 44: Line 60:
 
</pre>
 
</pre>
  
−
Feel free to organize documents in whatever way makes sense, but try to use a structure that is easy for other members to update.
+
Feel free to organize documents in whatever way makes sense, but try to use a structure that is easy for other members to update. This page, for example, does not use the above format.
  
 
==Wiki syntax==
 
==Wiki syntax==
Line 69: Line 85:
 
<i>italics</i>
 
<i>italics</i>
 
<b>bold</b>
 
<b>bold</b>
 +
</pre>
 +
 +
===Lists===
 +
 +
====Bulleted====
  
 +
Use asterisks to create a bulleted list. Indent sublevels with extra asterisks.
 +
 +
<pre>
 +
* Acrylic
 +
** Red
 +
**Blue
 +
* Nitrogen
 +
* Solder wire
 
</pre>
 
</pre>
  
 +
Displays as:
 +
* Acrylic
 +
** Red
 +
**Blue
 +
* Nitrogen
 +
* Solder wire
 +
 +
====Numbered====
 +
 +
Use ''octothorpes'' to create a numbered list. Indent sublevels with extra ''octothorpes''.
  
−
===Lists===
+
<pre>
 +
# Write manifesto
 +
# Build ray gun
 +
# Use ray gun
 +
# Rule the world
 +
## Endless mac & cheese
 +
## Universal healthcare
 +
## Free education
 +
</pre>
 +
 
 +
Displays as:
 +
# Write manifesto
 +
# Build ray gun
 +
# Use ray gun
 +
# Rule the world
 +
## Endless mac & cheese
 +
## Universal healthcare
 +
## Free education
  
 
===Links===
 
===Links===
 +
 +
====External====
  
 
Enclose external links in single brackets. Type the URL, a space, and then the hyperlink text after the URL.
 
Enclose external links in single brackets. Type the URL, a space, and then the hyperlink text after the URL.
Line 81: Line 139:
  
 
<pre style="width:50%; display:inline;"> [https://familab.org/ FamiLAB.org] </pre> displays as [https://familab.org/ FamiLAB.org]
 
<pre style="width:50%; display:inline;"> [https://familab.org/ FamiLAB.org] </pre> displays as [https://familab.org/ FamiLAB.org]
 +
 +
 +
You will have to fill out a captcha to save a page with external links. Unfortunately, the captcha breaks a lot. Keep saving your changes or refreshing the page until the captcha appears above your edits. Fill out the captcha and click save.
 +
 +
====Internal====
 +
 +
Enclose internal links in double brackets. By default, using the page name will display the name as a link. Use a pipe to add different display text to the hyperlink.
 +
 +
<pre style="width:50%; display:inline;">"[[Hacker|Read more about hackers]]" vs "[[Hacker]]"</pre> displays as "[[Hacker|Read more about hackers]]" vs "[[Hacker]]"
  
 
===Images===
 
===Images===
 +
 +
Photos and diagrams of processes are incredibly helpful for learning. Use images whenever you think they can add to a document's value.
 +
 +
====Upload====
 +
 +
To upload an image to the Wiki:
 +
 +
# Go to the left sidebar
 +
# Under tools, click 'Upload File'
 +
# Choose a png, gif, jpg, or jpeg
 +
# Enter a descriptive file name and optional description
 +
# Click 'Upload File'
 +
 +
View all uploaded files here: [[Special:ListFiles]]
 +
 +
====Insert into document====
 +
 +
<br>
 +
 +
<pre style="display:inline;">[[File:File.png]]</pre> will display the full image in the document.
 +
 +
 +
<pre style="display:inline;">[[Media:File.png]]</pre> will link to the file outside of the page.
 +
 +
 +
To display a thumbnail and description with the image in a wiki page, use <pre style="display:inline;">[[File:File.png|size|thumb|orientation|alt text]]</pre>.
 +
 +
 +
'''Examples'''
 +
 +
<pre>[[Media:Familab_bw_engrave_01.png]]</pre>
 +
[[Media:Familab_bw_engrave_01.png]]
 +
 +
<pre>[[File:Familab_bw_engrave_01.png]]</pre>
 +
 +
<pre>[[File:Familab_bw_engrave_01.png|100px|thumb|right|FamiLAB logo]]</pre>
  
 
===Tables===
 
===Tables===
 +
 +
Tables are a pain. Just use the [http://www.tablesgenerator.com/mediawiki_tables MediaWiki Tables Generator] or HTML.
 +
 +
If you are unfamiliar with HTML tables, below is a basic HTML table and the corresponding markup.
 +
 +
{| style="background-color:#F8F9F9; padding: 1%;"
 +
| <table><tr><th>Column 1</th><th>Column 2</th></tr><tr><td>Content 1</td><td>Content 2</td></tr><tr><td>Content 3</td><td>Content 4</td></tr></table>
 +
| <pre><table>
 +
<tr><th>Column 1</th><th>Column 2</th></tr>
 +
<tr><td>Content 1</td><td>Content 2</td></tr>
 +
<tr><td>Content 3</td><td>Content 4</td></tr>
 +
</table></pre>
 +
|}
 +
 +
HTML 'th' elements are headers, 'tr' elements are rows and 'td' elements are cells.
 +
 +
 +
==External Links==
  
 
===Resources===
 
===Resources===
−
Thanks to [User:LloydBlack Lloyd] for gathering this great list of Wiki resources!
+
Thanks to [[user:LloydBlack| Lloyd Black]] for gathering this great list of Wiki resources!
  
 
* [https://en.wikipedia.org/wiki/Help:Cheatsheet Wikipedia-Help:Cheatsheet] - Brief guide to wiki markup.
 
* [https://en.wikipedia.org/wiki/Help:Cheatsheet Wikipedia-Help:Cheatsheet] - Brief guide to wiki markup.
Line 95: Line 216:
 
* [http://www.tablesgenerator.com/mediawiki_tables MediaWiki Tables Generator] - Wizard for making basic wiki tables.
 
* [http://www.tablesgenerator.com/mediawiki_tables MediaWiki Tables Generator] - Wizard for making basic wiki tables.
  
−
==Editing for usability==
+
===Wiki Markup Help Pages===
 +
This list of Wiki Markup Help pages is for anyone who wishes to work on the FamiLAB wiki. It's not just for the Wiki Team. It's presented as a quick reference resource so editors can work on the wiki with better productivity.
 +
====Basic Markup Help Pages====
 +
*'''[https://en.wikipedia.org/wiki/Help:Cheatsheet Cheatsheet - Basic Markup Formatting]'''
 +
*'''[https://en.wikipedia.org/wiki/Help:Wikitext WikiText -  Markup Syntax Information]'''
 +
*'''[https://www.mediawiki.org/wiki/Help:Formatting Text Formatting]'''
 +
*'''[https://meta.wikimedia.org/wiki/Category:Editor_handbook Editor Handbook - Quick Listing of Many Help Pages]'''
 +
====Advanced and Specific Formatting Markup Help====
 +
*'''[https://www.mediawiki.org/wiki/Help:Lists Making Lists]'''
 +
*'''[https://www.mediawiki.org/wiki/Help:Images Image Handling Syntax]'''
 +
*'''[https://www.mediawiki.org/wiki/Help:Templates Making Templates]'''
 +
*'''[https://meta.wikimedia.org/wiki/Help:Advanced_templates Advanced Templates]'''
 +
*'''[https://www.mediawiki.org/wiki/Help:Tables Making Tables]'''
 +
*'''[http://www.tablesgenerator.com/mediawiki_tables Wiki Tables Generator - Tables Wizard]'''
 +
*'''[https://www.mediawiki.org/wiki/Help:Magic_words Magic Words - Wiki System Variables]'''
 +
*'''[https://www.mediawiki.org/wiki/Manual:Magic_words Advanced Magic Words Wiki System Variables]'''
 +
 
 +
===Other excellent Maker/Hackerspace Wikis===
 +
Use these as examples/inspiration.
 +
* [https://www.i3detroit.org/wiki/Main_Page I3Detroit].
 +
* [https://wiki.nycresistor.com/wiki/Main_Page NYC Resistor] .
 +
* [http://wiki.artisansasylum.com/index.php/Main_Page Artisan's Asylum]
 +
 
 +
 
 +
 
 +
[[Category:FamiLAB Wiki]]

Latest revision as of 01:45, 8 June 2019

So you want to contribute to the wiki? Welcome!

FamiLAB is an ever-growing and changing community. Our space adds new tools and new classes all the time, and walking into those changes can be a little overwhelming. That's why it's important to keep our Wiki up to date.

This page includes an overview of Wiki style syntax (all the weird, nonintuitive symbols you have to use to make it readable), as well as tips on writing your content.

TODO: Sheet of all Wiki pages, last edit date and status.

Gathering information

The first step to contributing is research.

Define a goal for your user content. It may already be in the title of the page (ex. "How to Turn on the Laser Printer"), or you may need to ask other members what they want to know (ex. something more vague, like "Biohacking". Is the article "What is Biohacking"? Is it "Getting Started with Biohacking"?).

The following is @bot's personal information gathering process:

  1. Figure out what the heck you're writing about.
  2. Write questions. What would you ask as a user? Is this dangerous? What does that red button do? Save those questions for later.
  3. Contact the expert. See if they can set aside time to show you the procedure. Send them your questions and the scope of your article so they can prepare. If you're the lab's resident expert, draft the procedure before you execute it.
  4. Observe the procedure. Keep notes to a minimum by recording it (ask permission first, of course). You don't have to share the recording, but it will be helpful to reference while you write the procedure steps. Do the procedure yourself if it helps you learn.
  5. Write! This is the fun part. Throw together a draft on the Wiki. It doesn't have to be perfect.
  6. Review. Ask the SME (Subject Matter Expert) and another member to review your document. They can check for accuracy and embarrassing typos.
  7. Test. This can be as easy as doing the procedure yourself, following along with your article. Collect user feedback. Edit as needed!

All Wiki contribution helps! Don't be afraid to ask for help finishing a Wiki page if it's outside of your comfort zone. The hardest part is starting, and you've done that just by reading this page.

Help article organization

For the sake of simplicity, we're going to refer to most Wiki pages as 'Help Articles'. For the most part, Wiki pages are basically Standard Operating Procedures (SOPs) for the Lab.

Here is a suggested structure to start your document. You can copy and paste this if you like: 

__TOC__
==Overview==
<!--A description of the tool/process/procedure. Keep it about 3-5 sentences. -->
==Get Started==
<!--A basic tutorial so the user is comfortable COMPLETING a task. -->
<!--If this is a more advanced doc, this section can be titled ==Procedure==-->
===Summary=== 
<!--Ex. "We are going to use the Thingajig5000 MicroMagicator to make a basic sparkle amulet. This process takes about 15 minutes to prepare, 20 minutes to execute, and 5 minutes to clean up."-->
===Definitions===
<!--If a user may not know what 'thermbibulate' means, define it here.-->
'''Thermbibulate''' - to gently agitate a solution of 50% wonderflonium and 50% Sprite Remix; used to rapidly heat theoretical matter.
===Cautions===
<!--Describe things that could damage a tool or ruin the product of a procedure. Explain how to avoid them.-->
===Warnings===
<!--Describe things that CAN KILL OR MAIM YOU. Explain how to avoid them.
===Qualifications===
<!--If a machine needs prerequisite knowledge, ex. GCode or an introductory class, say so. Provide resources here.-->
===Equipment and Supplies===
<!-- List materials for the project, rags for cleaning, hair spray for 3D printing, anything along those lines. -->
===Procedure===
<!-- Use numbered steps in this section. Keep commands simple.-->
==Feedback and Assistance==
<!-- Link to the experts. Who do I call if I break something? Who do I call if I don't know how to fix the thing I made?-->
==References==
<!--Helpful links and related Wiki pages-->

Feel free to organize documents in whatever way makes sense, but try to use a structure that is easy for other members to update. This page, for example, does not use the above format.

Wiki syntax

Headings & Structure

Surround headings with equals signs ( = ), starting with 2 equals signs for the highest level header. 

==Header 1==
===Header 2===
====Header 3====

Bold/Italics

Use apostrophes to change font weight and style. HTML tags are also recognized by Wiki markup.

Use 2 apostrophes to italicize. Use 3 apostrophes to make text bold. 

''Italics''
'''bold'''
<i>italics</i>
<b>bold</b>

Lists

Bulleted

Use asterisks to create a bulleted list. Indent sublevels with extra asterisks. 

* Acrylic
** Red
**Blue
* Nitrogen
* Solder wire

Displays as:

  • Acrylic
    • Red
    • Blue
  • Nitrogen
  • Solder wire

Numbered

Use octothorpes to create a numbered list. Indent sublevels with extra octothorpes. 

# Write manifesto
# Build ray gun
# Use ray gun
# Rule the world
## Endless mac & cheese
## Universal healthcare
## Free education

Displays as:

  1. Write manifesto
  2. Build ray gun
  3. Use ray gun
  4. Rule the world
    1. Endless mac & cheese
    2. Universal healthcare
    3. Free education

Links

External

Enclose external links in single brackets. Type the URL, a space, and then the hyperlink text after the URL. 


 [https://familab.org/ FamiLAB.org]
displays as FamiLAB.org


You will have to fill out a captcha to save a page with external links. Unfortunately, the captcha breaks a lot. Keep saving your changes or refreshing the page until the captcha appears above your edits. Fill out the captcha and click save.

Internal

Enclose internal links in double brackets. By default, using the page name will display the name as a link. Use a pipe to add different display text to the hyperlink. 

"[[Hacker|Read more about hackers]]" vs "[[Hacker]]"
displays as "Read more about hackers" vs "Hacker"

Images

Photos and diagrams of processes are incredibly helpful for learning. Use images whenever you think they can add to a document's value.

Upload

To upload an image to the Wiki:

  1. Go to the left sidebar
  2. Under tools, click 'Upload File'
  3. Choose a png, gif, jpg, or jpeg
  4. Enter a descriptive file name and optional description
  5. Click 'Upload File'

View all uploaded files here: Special:ListFiles

Insert into document


[[File:File.png]]
will display the full image in the document. 


[[Media:File.png]]
will link to the file outside of the page.


To display a thumbnail and description with the image in a wiki page, use 
[[File:File.png|size|thumb|orientation|alt text]]
.


Examples 

[[Media:Familab_bw_engrave_01.png]]

Media:Familab_bw_engrave_01.png 

[[File:Familab_bw_engrave_01.png]]
[[File:Familab_bw_engrave_01.png|100px|thumb|right|FamiLAB logo]]

Tables

Tables are a pain. Just use the MediaWiki Tables Generator or HTML.

If you are unfamiliar with HTML tables, below is a basic HTML table and the corresponding markup.

Column 1Column 2
Content 1Content 2
Content 3Content 4
 
<table>
<tr><th>Column 1</th><th>Column 2</th></tr>
<tr><td>Content 1</td><td>Content 2</td></tr>
<tr><td>Content 3</td><td>Content 4</td></tr>
</table>

HTML 'th' elements are headers, 'tr' elements are rows and 'td' elements are cells.


External Links

Resources

Thanks to Lloyd Black for gathering this great list of Wiki resources!

Wiki Markup Help Pages

This list of Wiki Markup Help pages is for anyone who wishes to work on the FamiLAB wiki. It's not just for the Wiki Team. It's presented as a quick reference resource so editors can work on the wiki with better productivity.

Basic Markup Help Pages

Advanced and Specific Formatting Markup Help

Other excellent Maker/Hackerspace Wikis

Use these as examples/inspiration.

Retrieved from "http://old.familab.org/wiki/index.php?title=Wiki_Help&oldid=14466"