View source for Policy Creation and Formatting Guide

==Policy Structure==

When editing or creating policy, the first thing to understand is what all of the different parts of our policy are.


At the top we have our [[Articles of Incorporation]]; these define our organization as far as the state of california is concerned. they cannot be changed easily and don’t ever really change.


Next we have our [[By-Laws]]; these lay down the fundamentals of our organization and how it functions. They do things like lay out what powers board and the committees  and executive have, and define the way that our meetings and voting and things like that work. These also don’t change very often, and are designed to be relatively constant. 


After that we have what is actually referred to as the [[Policy Directory]]. These is where the bulk of our actual policies are, and these are the ones that we typically change or add to on board. If you are creating a new policy, chances are it belongs in one of the sections of the Policy Directory. The policy directory is divided into seven sections, enumerated by roman numerals. Section II, membership and housing, is also referred to as the [[Administrative Code (AdCode)]] and is sometimes organized separately from the rest of the policy manual. The important distinction with the AdCode is that AdCom (the administrative committee) has the power to grant exceptions to the AdCode, but not to the rest of the policy manual. 


Before going on it’s worth mentioning that there are a few the policies that don’t fall inside of the policy directory. most notably is the [[Personnel Code (PerCode)]], which is a set of policies governing our employment practices. There are also both the [[Member Contract]] and the [[Employee Association Contract]] that live with the policies but are not in the policy directory as such. In addition to these there are a few other miscellaneous policies that don’t fall under the scope of the policy directory, and a whole slew of informational documents (found in the appendices for now) that lay out general practices but are not actually organizational policies. 


Getting back to the policy directory, each section is divided into several subsections, marked by upper case latin letters (e.g. I.A, I.B, IV.E etc.). On the wiki site, each of these subsections has its own page. If you are writing a new policy, you are most likely going to be adding to one of these subsections, or possibly creating a new one. A quick conversation with the operations manager is usually the best way to figure out where your policy should be located in the policy directory. It is possible that you need to change policy language in several sections. Searching the policy wiki for key terms is a good place to start looking for what parts of the policy you might need to edit.


Within each subsection of policy, sometimes there are divisions into numbered articles (I'm not sure if they are technically articles, but I'm going to call them that for our purposes). Unfortunately right now there is almost no standardization to how the policy is formatted within each article. Some have just paragraphs of text, others have numbered clauses, yet others just have lots of embedded lists. Ideally policy is structured something like [[IV.G. Business Conduct Policies]], where each article has a general paragraph at the top, and is then divided into paragraphs A. B. C. etc. as needed, with the occasional numbered list inside of these paragraphs. Occasionally you might need a sublist inside one of these list items (See [[http://bsc.coop/policy/index.php?title=IV.G._Business_Conduct_Policies#IV.G.7._PROTECTION_OF_RECORDS_-_FEDERAL_MATTERS | IV.G.7 B.4]]), but you should avoid excessive use of embedded lists (see [[VII.D. BSC Harassment Grievances Procedure]] for a policy that is bordering on excessive).

==MediaWiki formatting - BSC style==

We use mediawiki as the platform for our wiki website. It's the same platform that wikipedia uses, and is very popular, which means that there are lots of very good resources at hand for learning to use it. When in doubt, check out http://www.mediawiki.org , specifically the [http://www.mediawiki.org/wiki/Category:Help help pages], and most specifically the [http://www.mediawiki.org/wiki/Help:Formatting formatting help page]. I constantly refer to that formatting help page to remember how to do certain things. 

For now, we will run through the basics of the formatting syntax and best practices we will need to write BSC policy. It's not hard, I promise. The best way to learn is to start looking at the 'edit' pages and trying it out yourself. As you read this, I encourage you to click on the 'edit' tab at the top of this page as well as on some other policy pages to see how things are built. You can also use the [[Sandbox]] to play around and test different things as much as you want.


===Basics===
A few quick basics:
*Use <nowiki>two apostrophes like ''this''</nowiki> to make things ''italic'', and <nowiki> '''three'''</nowiki> to make things '''bold'''. You can even use five to make '''''both at once!'''''
*Single line breaks are ignored. To insert a line break, you have to leave a blank line. If you want a blank line to appear, enter TWO blank lines, etc.


===Headings===

Headings on mediawiki are made by putting the heading inside of equals signs like this: 

<code><nowiki>===This is a heading===</nowiki></code>

The number of equals signs you use determines the size of the heading, with more equals signs making smaller headings. The largest size heading, level 1 headings, are only used for the main title of each page and should not be used in the body of the page.


In this wiki, as a rule of thumb, each lettered subsection of the policy manual gets its own page (e.g. [[V.A. BSC Habitability Code | Policy directory V.A]]) with the subsection number and title as the name of the page. Within this subsection the policy will sometimes be divided further into articles (I'm not sure if they are technically articles, but I'm going to call them that for our purposes) that are numbered (look at [[V.B. HAPs Procedure]] for a simple example). Each articles should each have a level two headings, like this:

<code><nowiki>==II.A.1 Name of section two A, article 1==</nowiki></code>

The headings "Policy Structure" and "MediaWiki formatting - BSC style" on this page are level two headings for example. Subsections of policy that only have one article do not need a heading to number the article. Further subheadings below level two should not typically be used in actual policy, but can be useful in other documents (like this one! The heading "Headings" is a level 3 heading. woah.). See [http://www.mediawiki.org/wiki/Help:Formatting#Text_formatting_markup the MediaWiki formatting help page] for more information.

 
===Lists===
Most of our policy comes in a list of one form or another. Fortunately mediawiki has some pretty good tools for dealing with lists. You can check out http://meta.wikimedia.org/wiki/Help:List for all the details, but here are the basics:

'''Whenever possible, use the hashtag shortcut for making numbered lists.''' It works thusly:

When you type this:

<pre>
#Item one
#Item two
##Item two, subitem one
##Item two, subitem two
### Item two, subitem two, subsubitem one. You can embed these as many layers down as you would like, although it is probably not advisable to go more than a few layers deep.
#item three
</pre>

It will come out looking like this:

#Item one
#Item two
##Item two, subitem one
##Item two, subitem two
### Item two, subitem two, subsubitem one. You can embed these as many layers down as you would like, although it is probably not advisable to go more than a few layers deep.
#item three


Using this has several advantages. One is that the list items will automatically be renumbered if you add or remove list items, and that the embedded lists will automatically have the correct enumeration (e.g. lowercase alpha, roman numerals, etc). Another advantage is that using this style for lists will automatically use hanging indents, which makes the layout look much nicer.


It is important to note that if you insert a line break anywhere in the list, it will restart the numbering, which should never happen in a page of policy. If you need more space between the sections of policy, you can use the html <nowiki><br></nowiki> tag (stands for line BReak). If you insert <nowiki><br><br></nowiki> at the end of an item, it will create a blank line after the item without restarting the numbering.


If you need to use a numbering system besides the default one (or are editing a policy that uses a different style), there are a couple ways to do it depending on the situation. The first is to use the shortcut for colon indents, like so:

if you type this:

<pre>
:B)Item one
:A)Item two
::i)Item two, subitem one
::ii)Item two, subitem two
:C)item three
</pre>

It will come out looking like this:

:B)Item one
:A)Item two
::i)Item two, subitem one
::ii)Item two, subitem two
:C)item three

It's very similar to hashtag lists, except it does not automatically do the numbering for you. This method also does not use hanging indents unfortunately. This option works well for simple lists. If you need a more complex list structure with specific enumeration styles at each level, you have to use the HTML<nowiki> <ol> </nowiki> (stands for Ordered List) and <nowiki><li></nowiki> (stands for List Item) tags. I won't go into the details of that here, but check out the [http://meta.wikimedia.org/wiki/Help:List lists help page] for the details, and look at [[VII.D. BSC Harassment Grievances Procedure]] for an example of it being used in our policy. Using full HTML tags comes out looking very nice, but is time consuming and cumbersome to work with.


===Links and Footnotes===
To link to another page in the wiki, the syntax works like this:

<code><nowiki>[[Name of Wiki Page | text that appears as the link]]</nowiki></code>

For example, you could write:

<code><nowiki>Refer to [[Section IX: Semester Rates | Adcode Section IX.B]] for more details.</nowiki></code>

And it would appear as:

Refer to [[Section IX: Semester Rates | Adcode Section IX.B]] for more details.

If you reference another policy on a page, you should create a hotlink for it. For more details about links check out http://www.mediawiki.org/wiki/Help:Links. 


To create a footnote, eventually we will be using [http://www.mediawiki.org/wiki/Extension:Cite/Cite.php the cite plugin] that will make footnotes really slick, but until we get that up and working you can insert them manually by using the <nowiki><sup></nowiki> tag to create superscripts<sup>1</sup>, and putting the footnote at the bottom of the page under a horizontal line (which is made with four dashes). You can check the 'edit' tab for this page to see how it works.


===Tables===

Creating tables can be useful to organize data, but can be a little tricky. There is no easy-to-edit "spreadsheet" feature that you can use to create a table. Rather, you have to fill out the table using regular text markup, in a specified way. Once you get a sense for how that works, though, creating a table isn't that hard. There is a very thorough guide to creating a table [http://en.wikipedia.org/wiki/Help:Table here].


==General Editing Practice==
When you are editing the wiki, it is important to keep good documentation of what you are doing so that people looking back will be able to tell when we created certain policies and what their histories are. 


To create a new wiki page, either search for the page title that you want, or create a link to the page that you want and then click on it. Links that lead to currently non-existant pages will appear as red, and when clicked will give you the option to create the page.


When editing a page, there is a text box labeled "Summary" by the "Save Page" button. '''If you are changing policy content, enter the date of the board meeting that the change was approved in the summary box''', along with any other useful information. For example you could write "Added a new clause to section B of the substance abuse policy - passed at 2/5/11 board meeting".  Enter whatever you think would be useful to someone looking back at a list of edits and trying to figure out what each one was.

In addition, update the log at the bottom of the wiki page with the date that the proposal went to Board so someone looking at the policy can quickly get a sense of it’s history without going through revision history (most recent dates first). It should look something like this: ''[Board Approved: 4/28/2011; 11/4/2010;]'' If there is no log, add one using this format: <code><nowiki>''[Board Approved: xx/xx/xxxx;]''</nowiki></code>


When editing or adding policy '''use the "Show preview" button to check the formatting until you have the policy completely entered and formatted correctly.''' If possible, you only want to hit "Save page" once, after the whole policy has been typed in and formatted. This will avoid having a really long list of small edits that were made. As wiki editing goes, you will inevitably find some formatting issues or typos that you have to go back in and change. '''When doing so, check the "This is a minor edit" button,''' so that it is clear in the edit log that you are just changing format, and not content. 


----
1. This would be footnote number one.