Policy Creation and Formatting Guide: Difference between revisions

From BSC Policy
Jump to navigationJump to search
xx>Willkrantz
No edit summary
xx>Willkrantz
No edit summary
Line 14: Line 14:




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])
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==
==MediaWiki formatting - BSC style==
Line 99: Line 99:
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.
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 in your policy, you should create a hotlink.






bold and italics
headings
spacing
lists
links/references
links/references
overall structure
overall structure
making changes


common tips and tricks:
common tips and tricks:


dont start lines with a space!
dont start lines with a space!

Revision as of 13:58, 15 June 2011

Policy Structure

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 bylaws; these lay down the fundamentals of our organization and how it functions. it does things like lay out what powers board and the committees and executive have, and defines the way that out 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 AdCode (Administrative code) 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. [check with kim about this]

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 Personal 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 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


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 | 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.mediawik.org , specifically the help pages, and most specifically the 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 two apostrophes like ''this'' to make things italic, and '''three''' 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:

===This is a heading===

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 mentioned above, each subsection of the policy manual gets its own page (e.g. V.A or II.B) 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:

==II.A.1 Name of section two A, article 1==

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 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:

#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

It will come out looking like this:

  1. Item one
  2. Item two
    1. Item two, subitem one
    2. Item two, subitem two
      1. 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.
  3. 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 <br> tag (stands for line BReak). If you insert <br><br> 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:

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

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 <ol> (stands for Ordered List) and <li> (stands for List Item) tags. I won't go into the details of that here, but check out the 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:

[[Name of Wiki Page | text that appears as the link]]

For example, you could write:

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

And it would appear as:


Refer to Adcode Section IX.B for more details.


If you reference another policy in your policy, you should create a hotlink.


links/references overall structure making changes

common tips and tricks:

dont start lines with a space!