Difference between revisions of "Help:Tutorial"

From SNIC Documentation
Jump to: navigation, search
(Quickstart)
(Quickstart)
Line 11: Line 11:
 
: This is so that you won't have to scour pages upon pages of running text to chase down that one tag that someone set to something a little too funky at 17:08 one Friday afternoon. Here is the key to the secret: this wiki is entity based. All tabulatable information on an entity is found at the top of each entity's page, eg. software info at the top of each software's page, and so on and so forth. Press the Edit button on top of the page to go to the right place. All other buttons just let you edit that section, which is handy for large pages, but not much else.
 
: This is so that you won't have to scour pages upon pages of running text to chase down that one tag that someone set to something a little too funky at 17:08 one Friday afternoon. Here is the key to the secret: this wiki is entity based. All tabulatable information on an entity is found at the top of each entity's page, eg. software info at the top of each software's page, and so on and so forth. Press the Edit button on top of the page to go to the right place. All other buttons just let you edit that section, which is handy for large pages, but not much else.
 
; Installed software should be specified on the individual resources' pages.
 
; Installed software should be specified on the individual resources' pages.
: If you have installed a new software on a resource, go to that resource and add the software name to the list of installed software.
+
: If you have installed a new software on a resource, go to that resource and add the software name to the list of installed software. It may also be possible for you to generate lists of installed software from your module system (or similar) and then just paste that in. See for example [[File:Get_snicdocs_software_for_cluster.py |this helper]].
 
; Tabulatable information is called properties
 
; Tabulatable information is called properties
 
: They are documented and have semantics. See [[#Self-education]] below.
 
: They are documented and have semantics. See [[#Self-education]] below.

Revision as of 15:23, 11 January 2012

This document is designed to get you up to speed with adding content as quickly as possible. Therefore, it contains as little text as possible. If you have any trouble that your coworkers can't solve for you in 30s, please contact Joel Hedlund and we'll set you straight in a jiffy. If you need help creating pages, see Help:Creating pages. If you need help understanding the mediawiki text format or how to generate dynamic tables, see Help:Editing. If you're unsure as to what goes onto this wiki and what does not, see Help:Content policy. This page is for something else, namely to explain what sets snicdocs apart from other mediawiki installations out there. If there is something in here that is unclear, chances are that it is better explained in Help:Design, but I didn't want all those words in here. Go there if you want them.

Quickstart

Here is a list that will get you bootstrapped:

Only cert-regged people using https can edit. Others can only Talk.
Install your certificate in your browser if you haven't already, then go here: https://snicdocs.nsc.liu.se. You will be logged in automatically. See your name on top of page. No? Notify root@nsc.liu.se and they'll set you up. Unless you are thus set up, you can only edit Talk pages (aka Discussion pages, see tab on top of each page). Talk pages are a means for user feedback on site contents.
You cannot edit dynamically generated content in-place.
Scattered across the wiki you will see blue tables. They are views. You cannot edit them.
The obvious place to enter information is at the top of the page.
This is so that you won't have to scour pages upon pages of running text to chase down that one tag that someone set to something a little too funky at 17:08 one Friday afternoon. Here is the key to the secret: this wiki is entity based. All tabulatable information on an entity is found at the top of each entity's page, eg. software info at the top of each software's page, and so on and so forth. Press the Edit button on top of the page to go to the right place. All other buttons just let you edit that section, which is handy for large pages, but not much else.
Installed software should be specified on the individual resources' pages.
If you have installed a new software on a resource, go to that resource and add the software name to the list of installed software. It may also be possible for you to generate lists of installed software from your module system (or similar) and then just paste that in. See for example this helper.
Tabulatable information is called properties
They are documented and have semantics. See #Self-education below.
Most tabulatable info is entered through templates
Templates are functions. They look like this: {{name of template | arg1 | arg2 | named arg=value | nonsense=off}}. We do it this way so you won't miss entering something important, or enter it the wrong way. They're there to make it easier for you. See #Self-education below.
Most views are generated by templates
This is so that all views of a certain kind look the same, no surprises. And we can change them all in one go if need be. You know I said you can't edit the views? I lied. You can definitely break that black box right open and poke around in the juicy bits, copy relevant stuff out and change it slightly. Don't. For reasons already explained.
Use the example pages
We are holding your hand! For most stuff we have thought of, we have written an Example page that you can just copy and fill in with whatever details should go there. Presto!
Nothing goes live until you press "Save page"
Feel free to play around. To feel extra safe, use a semi-hidden page in your own private namespace, like for example this one: User:Joel Hedlund (NSC)/test. See what I did there? I just appended "/whatever" to my user page, and created a page that will not come up in searches, and whose name does not collide with anything else. Don't go adding any info using templates or categories on that kind of page though! That will drag them right back into the limelight, and we don't want any half-finished experiments turning up on stage, especially not if you think are being secretive with them! But they are very nice for drafting articles like this one. By the way, you can click your name on top of the page to go to your user page. How do I create the page then, you ask? Why, go read Help:Creating pages, under the heading "Create the page".
Read the docs for once
You know how you always tell your users to read the docs? Yeah. Go here: Help:Editing policies. Tell Joel Hedlund if things do not make sense or are missing.

Self-education

This is a wiki. It is dynamic. While it would be entirely possible to summarize and describe in detail what entities have what properties, how they should be used, and what each template does and how it works, it would be self-defeating and silly. The proper way of doing this is to self-educate and look at examples.

Exercise:

  1. Go to HMMER.
  2. Edit the page.
  3. Press "Show preview".
  4. Scroll to bottom.
  5. See list of templates used and properties set.
  6. You can click the template names to see the their documentation, or press the corresponding "(edit)" to see the source code. The source code looks awful because mediawiki uses an ad-hoc parser where whitespace matters (basically csh + LaTeX), but mostly it's simple string crunching and logic. Not even iteration. Google will happily tell you exactly what each bit of the template is doing. Or you can ask Joel Hedlund if you think that'll be quicker.
  7. At the very bottom, you can see a box that shows what properties are set on this page. You can click any property name to see its definition and semantics.
  8. See the little icon with arrowy things next to the box heading "Facts about HMMER"? There's actually quite a lot of those around these parts. Clicking them takes you to the Browse: interface for the corresponding page, where you can click around and explore what properties are set to what, and how they interconnect the pages on the wiki, complete with back links. The back links may be hidden under "show properties that link here", and if so: click the link to show them! There is also a shortcut to come here: just prepend any page name with "Special:Browse/" in the url.
  9. This works for all pages.
  10. Happy exploring!