Guide:The STEP Wiki

From S.T.E.P. Project Wiki

Contents

The STEPwiki editing guide for editors -- by S.T.E.P. Team

GUIDE FORUM THREAD


Weapon.png Under Construction: This page is incomplete but all info is relevant!


Definition of a wiki:

"a website or database developed collaboratively by a community of users, allowing any user to add and edit content."

The STEP wiki is intended to be community-driven; although, all STEP wiki contributions have originated from only a handful of STEP site contributors. Our goal is to make it easy for all community members to contribute and help us maintain existing content and develop new content. The first step in doing that is to make our user base more comfortable with the idea of working on a wiki and thinking in wiki terms.

Editing Tips

I moved this section from the Citizenship Guide, so it should be more properly integrated into this page content. Just straight pasting for now so we have it here. Feel free to integrate it! ~z929669 Ixian Insignia.png Talk 18:05, January 4, 2015 (EST)

A wiki is simply an integrated assemblage of articles (i.e., pages) containing information that usually links to other wiki pages (i.e., articles). Every internal wiki link points to another page. If the link is blue, the page exists, and if it is orange, the page is referenced, but has not been created. Feel free to click on orange links and create the page by adding something relevant and saving.

  • The wiki search bar is located at the bottom right of the browser window; however, can be found in the Wiki drop-down menu at the top of the page as well. Use this to find just about anything quickly.
  • From the Header bar at top, select WIKI > Recent Changes to get a look at the most recent activity on the wiki. This is often the most convenient way to find a project of interest (and to see who may be fiddling around lately).
  • Select TOOLBOX > SPECIAL PAGES and towards the bottom of the first list under "Maintenance Reports", there are links to "Wanted" pages. This means that someone has created an article with reference to information that is not yet defined (i.e., by creating the page).
  • The simplest way to get started on the wiki is to begin by playing around under your personal user page:
wiki.step-project.com/User:Username
  • Editing and general preferences can be set by user ... click on your user name at top-right in the header bar.
  • When editing a page, be sure to fill in the summary box below the editing space with what changes you made before saving that page. This summary will be logged on the Recent Changes page and helps everyone to know what exactly was added/changed with a given edit.

Wiki Basic Resources

Mediawiki
Home Page - Entry point to lots of relevant info, including reference and help as well as latest development and news
Help - MediaWiki's Help directory
Cheat Sheet - List of the most commonly used mediawiki markup
Tables - Wikitext syntax for tables
Magic Words - Behavior switches and variables
Parser Functions - Functions meant to provide more advanced logic
Semantic Mediawiki
Semantic Mediawiki - Documentation about Semantic MediaWiki ()see lower portion of middle frame).
Semantic Forms - Documentation about Semantic Forms, which provide a form-based interface for maintaining relevant SMW pages and content.
Semantic Forms Inputs - An extension for Semantic Forms
The STEP Wiki
(top bar) TOOLBOX --> SPECIAL PAGES - Links to all kinds of information about this wiki
(top bar) WIKI --> RECENT CHANGES - Links to all of the most recent edits on this wiki
Software used on this wiki - Software and versions with links to documentation.
HTML and CSS
CSS Resource - Not all info on this page is relevant but it contains various keywords that can be used
HTML Resource - Not all info on this page is relevant but it contains various keywords that can be used

Need Help?

Private message one of these guys if you need some sort of help with writing on the wiki.

Primary Wiki Editors/Maintainers

Always looking for others!

Recently active wiki editors

STEP Wiki Best Practices

General Edits

  • Please don't use heading code to make text bigger or bolder. Instead use wiki markup and/or the Fs template. Headings are for ... headings
  • Note that the wiki css controlling typography and text color has been tweaked recently. It is now best practice to use {{fc|#ddd|}} rather than {{fc|white|}} for text highlighting (i.e., skim text), because white is just too bright against the new, slightly darker body font without blaring too far past the brightened heading fonts.
  • More to come ...

Guides

This wiki has many, and they should all have the same general look and feel. Following are some basics ...

Guide Standard Header

Our guides (aside from the main STEP Guide) maintain a consistent look in part by following a specified formula. Please use the following format (placed just after TRANSCLUSIONS & CATEGORIES header format):

<!-- ########### STANDARD GUIDES HEADER FORMAT ############ -->
''Brief guide description here -- by Author(s) here''

[<forum thread URL> '''GUIDE FORUM THREAD''']
----
Add any relevant Notification Templates here
<br />

<!-- ######### END standard guide header format ########## -->

Writing Style

Guides in particular should be written in the third person. This is more clear and professional and not as prone to degenerating into a mess of first-second person reversions:
  • First person: "I first must click on the 'edit' button ..."
    Second person: "You first must click on the 'edit' button ..."
    Third person: "First, click on the 'edit' button ..."

Instructions

We need to be consistent in how we instruct a user to perform tasks. Follow these guidelines when writing instructions:

  • When instructing a user to 'click' or 'select' any UI element: use the {{ui}} template, as in the following example:
    • Click {{ui|Edit}}, then right click {{ui|some UI element}} ...
    • Click [Edit], then right click [some UI element] ...
  • When referring to messages in the UI: Italicize the UI message, and do not highlight it in any other way.
  • In-line headings: If you have several bullets or paragraphs in a row which each refer to a certain topic, you may use bold, peach-colored formatting to highlight the topic of each bullet or paragraph, as in the following example:
    • {{fc|#e6b693|'''First Topic Name.'''}} This paragraph explains the first topic. Other paragraphs will have their own in-line headers and explanations.
    • First Topic Name. This paragraph explains the first topic. Other paragraphs will have their own in-line headers and explanations.
    • Working Example

Text Coloring

For readability and consistency, use the {{fc}} template with one of the following color codes when applicable (see the template page for more info):

  • #9eb8ee (blue-ish) - Text relating to additions, enhancements, or confirmations.
  • #78c888 (green-ish) - Text relating to fixes, or functional/relevant things.
  • #ff7878 (red-ish) - Text relating to removals, or non-functional/irrelevant things.
  • #c0c840 (yellow-ish) - Text relating to issues or unknowns.
  • #f09800 (orange-ish) - Text relating to changes/modifications.
  • #e6b69e (peach-ish) - The important part of instruction text, or highlight an in-line header (see Instructions, above).
  • #ddd (white-ish) - Generally important text (not an in-line header or instruction-related).

Categories

Categories are used to topically associate wiki pages. They also provide a simple means to navigate and view associated pages. Simply scroll to the bottom of any page and follow the category links to view more pages within that same category. Assigning a page to a category is as simple as adding [[Category:<whatever>]] when editing the page. Categories can be referenced on a page without adding that page to the referenced category by adding a colon to the beginning of the code as such: [[:Category:<whatever>]]. Wiki editors are asked to:

  • Read about how to use categories.
  • Assign pages to the proper existing categories.
  • Avoid creating new categories --leave that to the site admin. Just let one of the administrators know or post about it in the guide forum thread linked at the top of this page.
  • Place the category code at the TOP of the page for consistency and to make it easy for other editors to find. Following is the standard format:
<!-- ############ TRANSCLUSIONS & CATEGORIES ############ -->
Add special templates, magic words, or categories here
<!-- ########## END transclusions & categories ########## -->

User pages

This is the User "main page" ... and entry-way into the user's personal sandbox. Each user can do just about anything they want in here as long as in accordance with the rules dictated within the STEP Community Citizenship Guide. Wiki editors are asked to:

  • Avoid editing a user's page without permission (not applicable to wiki administrators). While everyone can edit others' User: page, it is a breach of etiquette to do so.
  • Edit the page and add some information about themselves for others ... even a link to another website or their forum profile is a good start.
  • Other "Best Practices" for this wiki do not apply here ... User makes the call.

Use of HeaderTabs

Wiki guides should convert back over to the TOC method versus current HeaderTabs. HeaderTabs is still great for entry pages or other applicable content, but not so in the case of guides and similarly large pages with lots of content. Some guides now using HeaderTabs will need to be tweaked a bit in order to revert to TOC format in a 'nice' way, but all guide updates should be heading in that direction as time allows.

HeaderTabs Enabled

It is possible to link to tabs but not to sections beneath tabs. Linking to sections underneath tabs is not necessary when HeaderTabs is used 'properly' ... that is, when the tab content does not require much vertical space and one does not need to scroll down to see section headings. However, vertical space relies the dimensions of the browser window, which is in turn constrained by the display resolution, so any page using HeaderTabs should optimally exhibit this behavior. The problem is that to do so means that page organization must accommodate appearance first and information flow second, so large, complex pages do not lend themselves well to HeaderTabs format. Similarly, HeaderTabs also encourages misuse of headings (i.e., use of headings for typographical appearance rather than information management) ... there is a reason that Wikipedia and all of the major wiki sites default to TOC. Therefore, HeaderTabs should be limited to entry pages or relatively high-level pages and not extended to guides and other information references.

Link to HeaderTabs Tab

[http://wiki.step-project.com/HeaderTabs_Functionality#Using_DDSopt]

Link to HeaderTabs Section (beneath a tab) (Note that the link does not navigate to the intended tab section unless already on that tab)

[http://wiki.step-project.com/HeaderTabs_Functionality#File.2FPath_Browser_Toolbar]

HeaderTabs Disabled

All information is immediately accessible in a hierarchical format from the TOC the moment the page loads. This is fantastic for guides and other info references, but it is not desirable for small or relatively simple pages with few sections and subsections. HeaderTabs format is much better in such cases.

Link to Normal Page Section

[http://wiki.step-project.com/TOC_Functionality#File.2FPath_Browser_Toolbar]

HeaderTabs Summary

Use HeaderTabs when...

  • The page is relatively simple
  • When primary topics (H1 headings) are minimal ... say, 5 tabs or fewer
  • Tab content fits in a single 1280x1024 window without needing to scroll down
  • The page is an entryway into related content

... else, please avoid using HeaderTabs in favor of the TOC method described above.

Warning-Logo.png      Warning:Don't use [PAGE TOOLS] → [EDIT EXTERNAL] That feature is deprecated in MediaWiki and requires a lot of user configuration to function correctly.

Page Management

How to create, delete, edit and manage a wiki page.

Creating a Page

To create you own page that is in your User namespace

  1. Make sure that you are logged into the wiki by looking at the top right hand corner of the page.
  2. In the URL type "http://wiki.step-project.com/User:<username>/<subpage>
  3. In the <username> field type YOUR user name
  4. In the <subpage> field type the title of the page.
  5. Then in the Top Right hand corner of the page click on the [PAGE TOOLS] button and select CREATE
    • To create a page you must have something on the page to Save it.
    • Some writers have found that typing "Hi" or "== Introduction =="is good enough to get things moving.


Deleting a Page

X

Magic Words

Magic words are special 'text strings' that are used by the wiki software to return values or functions. A full description of them can be found on the MediaWiki website.

Common Magic Words

X

Symbols

Search for HTML symbols and use a code like "#8594;" with an ampersand "&" in front of it to produce "→"

Formatting Basics

This will hold the dos, donts and good habits with formatting but be focus on where to look for the info.
Like the cheatsheet...

Inline HTML and CSS

I believe that is what the span style tag is. This will give some common usages that are on step but will will guide the user to a link for what styles are valid like such

Using Templates

Templates can be found in [TOOLBOX] → [SPECIAL PAGES] → [Templates]
Here is a direct link

Some of the more common Templates that are used on the STEP wiki are:

Info-Logo.png Notice: The code for this is: {{notice|text=text for the notice}}
Warning-Logo.png Warning: The code for this is: {{warning|text=text for the warning}}

Some are used for links, either to other pages in the current wiki or to outside pages. The following is a link to a chapter in the current document that also has a 'tabbed' header, such as the Mod Organizer wiki:

{{#switchtablink:Profiles|Profiles}}

YouTube videos can also be linked to with code like this:

{{Video|j4ZQpzf_iAE|Mod Organizer: Introduction (by Gopher)|Gopher Explains Mod Organizer}}

Here the magic word Video is read as https://www.youtube.com/watch?v= and j4ZQpzf_iAE, the YouTube address for that specific video, is appended to the YouTube code to provide a valid address. Clicking that link will display a popup window of that video file.

Using Forms

Placeholder.

Wiki Development

Placeholder.

Creating Templates

Placeholder.

Creating Forms

Placeholder.

References