SSFWiki:Help

Some hints and tips for contributing to the work on this site. The first section is just one person's impressions, if you want to see a more reliable, and much more complete piece, go straight to here.

The most important tip is to experiment. Use the 'Show Preview' button to see what you've created, look at the code for pages you like the look of by hitting 'Edit this page' to see how others have done stuff. If you're nervy about messing stuff up, go and play in the Sandpit.

The Basics
Wiki is a flexible, relatively easy-to-use piece of software that enables groups to work together on documents on the web. The benefits to this are:
 * Anyone with an internet connection can take part - no software other than your normal internet browser is required.
 * There are very few compatibility issues, so almost any internet-worthy computer system should do.
 * There's no confusing back-and-forth sending of documents required.
 * Its an entirely open process of working, anyone can see all the stages that have got to the project to the point its at.

But, there is some stuff that needs to be learnt to make use of the best features of Wiki pages. Making a few basic points clear at the beginning might help (with apologies to genuine techies, cringing at my misunderstandings); fundamentally,
 * 1) Text works differently on the web than it does in your usual text editing packages (eg Word). For example:
 * 2) *For Wiki pages you can't set the font or size of the body text, this is already set for the whole site.
 * 3) *Instead of formatting the text you see when creating a webpage you must insert markers (called 'markup') into the flow of the text, around any text that requires special formatting. For example, instead of highlighting a word to make it bold, you put three apostrophes on each end of the word to signal the browser to emboldent the text.
 * 4) *Also, web code has little respect for gaps of any kind, and will try to let text flow from one side of the screen to the other, even if you've pressed enter! So, you need to actively tell the browswer either by putting  at the end of the line, inserting a whole blank line (referred to as 'newline') by hitting enter twice, or by starting the next line with some list formatting such as bullets (insert *) or numbers (insert #).
 * 5) *This means that the text formats you see when creating a web page is not the same as will appear in the browser. Which is why there is a 'show preview' button at the bottom.
 * 6) *The various differences seem to be to reduce the information required to tell your browser how to make the page (decreasing download times) and to increase the compatability with different systems, screen sizes, font sets and so on.
 * 7) A Wiki is a bit like a web within a web. (Or some such nonesense. I've always considered the web and net metaphors a bit ropey (hah!), because webs and nets are evenly spaced out.  The internet is more like one of those webs made by spiders on drugs.)
 * The point is that some pages are densly linked together, as should wiki pages. Wiki makes it easy to create new pages: go to an existing page and enter a relevant comment that you want to link to the new page; insert a key word(s) in [[double square brackets]] and it will be highlighted.  Save the page, click the new link and you will go to your brand new page.

To (Easily) Edit a Page
All you really need to know is the following:
 * 1) Click 'Edit this page' to start.
 * 2) Type text directly into the large box in the middle of the screen. When you view the page normally this will appear in the appropriate font, wrapped appropriately within the screen - no need to end lines by hitting Enter/Return.
 * 3) Just hitting Enter/Return will not give a new paragraph on normal viewing of the page. For a new paragraph you need to hit Enter/Return twice (leaving a whole blank line in the Editing page) or end the line with   (including angled brackets).
 * 4) You can add headings and format text in the following ways:
 * 5) *To create a heading surround the heading text in equals signs (=). There are three differently formatted levels, indicated by having one (biggest text), two or three equals signs at both the beginning and end of the heading text.
 * 6) *To create a bulleted list add an asterix (*) to the beginning of each line you want to start a new point.
 * 7) *To create a numbered list, do the same with hash marks (#).
 * 8) *You can italicise text with two apostrophes at each end of the word(s).
 * 9) *You can embolden with three apostrophes at each end of the word(s).
 * 10) *And you can combine the two using five.
 * 11) Click 'Show preview' to check exactly what the text will look like before you save the page. Scroll down to the bottom of the page and you'll find your editing box again.  Hit 'Show preveiw' to refresh.
 * 12) Add a comment in the 'summary' box and hit 'Save page' to finish.
 * 13) Don't Panic - even if you mess it up completely and have saved the page, all the previous states of the page can be accessed and everything put back in order. If you're stuck email the [mailto:ssf-tech@email-lists.org tech list] for help.

More Detail
The full list of Wiki markup - that's the coding that gives you formatting and so on - with instructions on creating hyperlinks (to other external webpages and to pages on the SSF Wiki itself) and so on is available here.

Top tip: have that web page open in another window while writing Wiki pages for quick reference.

Etiquette and Style
In terms of etiquette the Wiki types say don't be timid about changing other people's work, just go for it. Along with this, we should not be too precious about our own writing. We're all taking part in a collaborative effort, and people only generally change to improve pages.

In terms of style, we can decide what we want, so maybe people should contribute to the following lists:

Things we like

 * Tidyness. People come to the wiki directly from the WWW website and don't necessarily realise its work in progress.  Please keep things tidy and clear to understand, otherwise no one will read it anyway.  If you've started a page please take some responsibility for tidying it up from time to time.
 * Bullet points for lists.
 * Blank lines for new paragraphs.
 * Logging in to make changes, and using the 'Summary' box on the edit page (this appears on the list of Recent Changes).

Things we don't like

 * Lots of exclamation marks or questions marks - like this!?? (Only use a single exclamation mark, and only if you really can imagine someone exclaiming the sentence.)
 * Time specific headings like: "Latest version" or "Saturday's comments". Use the full date if relevant.
 * Headings or other elements IN ALL CAPS.

Stuck?
If you're really flummoxed but want to add stuff to the wiki then send a simple text file (with no formatting) to the [mailto:ssf-tech@email.lists.org tech list]. You can use the same link to ask questions and, if you're lucky, have them answered.