Difference between revisions of "Wiki Help"
(Moves "Wiki Markup Help Pages" info from Wiki Team article to this article.)
m (Fixes category.)
|Line 241:||Line 241:|
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.
- 1 Gathering information
- 2 Help article organization
- 3 Wiki syntax
- 4 External Links
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
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.
Headings & Structure
Surround headings with equals signs ( = ), starting with 2 equals signs for the highest level header.
==Header 1== ===Header 2=== ====Header 3====
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>
Use asterisks to create a bulleted list. Indent sublevels with extra asterisks.
* Acrylic ** Red **Blue * Nitrogen * Solder wire
- Solder wire
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
- Write manifesto
- Build ray gun
- Use ray gun
- Rule the world
- Endless mac & cheese
- Universal healthcare
- Free education
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.
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"
Photos and diagrams of processes are incredibly helpful for learning. Use images whenever you think they can add to a document's value.
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
[[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
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.
<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.
Thanks to Lloyd Black for gathering this great list of Wiki resources!
- Wikipedia-Help:Cheatsheet - Brief guide to wiki markup.
- Wikipedia-Help:Wiki markup - Wiki markup language.
- MediaWiki-Help:Formatting - Help with formatting wiki pages.
- MediaWiki-Help:Tables - Table markup for adding tables to wiki pages.
- MediaWiki Tables Generator - Wizard for making basic wiki tables.
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
- Cheatsheet - Basic Markup Formatting
- WikiText - Markup Syntax Information
- Text Formatting
- Editor Handbook - Quick Listing of Many Help Pages
Advanced and Specific Formatting Markup Help
- Making Lists
- Image Handling Syntax
- Making Templates
- Advanced Templates
- Making Tables
- Wiki Tables Generator - Tables Wizard
- Magic Words - Wiki System Variables
- Advanced Magic Words Wiki System Variables
Other excellent Maker/Hackerspace Wikis
Use these as examples/inspiration.