Difference between revisions of "Clicklaw Wikibooks Contributor Guide"

From Clicklaw Wikibooks
Jump to navigation Jump to search
Line 231: Line 231:
There are several ways to embed an image — however only a couple work well in support PDF, EPUB, and print-on-demand viewing. Consistency is important, so please use the following approach:
There are several ways to embed an image — however only a couple work well in support PDF, EPUB, and print-on-demand viewing. Consistency is important, so please use the following approach:
Writing this:
Writing this:
:<tt><nowiki>[[File:DescriptiveImageName.jpg| right | frame | link=| <span style="font-size:60%;">Copyright Information</span>]]
:<tt><nowiki>[[File:DescriptiveImageName.jpg| right | frame | link=| <span style="font-size:60%;">Copyright Information</span>]]</tt></nowiki>


... should produce this:<br />
... should produce this:<br />

Revision as of 22:52, 7 August 2014

This is a help page for contributors or users.


This is a guide for editors and contributors who have accounts with Clicklaw Wikibooks, and who are actively responsible for editing content. Read on to learn how to:

  • Log in
  • Make changes on a page

The Clicklaw Wikibooks Contributor Guide is designed to get editors and contributors started. If you are not a Clicklaw Wikibooks contributor, but are a Clicklaw contributor for the main Clicklaw website and need support, please see the Clicklaw Website Contributor Guide.

Getting started

Authors, editors and reviewers

Clicklaw Wikibooks houses content for a number of publications, each of which has its own arrangement with its contributors (authors, editors and reviewers). Some wikibooks, such as those produced by Peoples Law School, are administered by a small team of editors only, while other wikibooks, such as JP Boyd on Family Law, involve numerous collaborators such as subject editors, senior subject editors and editors emeritus.

Before you edit

Know what you're responsible for

Have you been invited to edit a particular title? Are you certain the page you're about to edit is part of the right wikibook title, and does not belong to a different wikibook?

Be conscientious about which page you are editing. Please only edit pages from those titles (or chapters within titles) for which you are responsible. Generally, let your discretion guide you, or email wikisupport@clicklaw.bc.ca for help.

That said...

Relax, you can't screw up

Having asked you to be mindful of the pages you edit, take comfort in knowing that you literally can't damage a page so badly that it cannot be restored. One of the best things about this wiki platform is that each page has a "History" of older versions, including the one you just saved over. You (or another person) can always undo an edit and restore an older version of a page.

When viewing a page's history tab:

  • Selecting Undo on the current version will show you the difference between it and the next most recent version, and you can then select "Save page" to restore the earlier of the two versions.
  • Selecting Rollback on the current version of a page will undo all of the recent changes by the contributor who had saved that current version, with the effect of rewinding the page back to the most recent version saved by someone other than that contributor.

If we haven't taught you how to do it, ask us how (or leave it be)

A minimum knowledge of the tools is required. Other than knowing how to log in, navigate around, and where to find things like the "Edit" tab, you will need to know how to:

  1. create (or fix) links to cases, legislation, other web resources,
  2. make lists (like this numbered list),
  3. create emphasis for key words or documents using italics, or in rare cases bold,
  4. divide pages with section headings and subheadings,
  5. indent paragraphs or blocks of text,
  6. create text in a plain format (for legislation excerpts), and
  7. understand a few technical things that are happening and the limited things you need to know to:
    • change what alert boxes are saying on pages,
    • work with your contributor bio page,
    • understand some of the weird coding and know what to leave alone,
    • maybe change the contents of tables, and
    • participate in Discussion pages (these are locked down so only editors can see Discussions about a page).

This page shows you how to do the above. You are not expected to do anything technically beyond what is explained here. If you have questions, email us at wikisupport@clicklaw.bc.ca

Logging in to your new account

Everyone who contributes to Clicklaw Wikibooks will be given an account. All of your work is linked to your account, so it’s important to use the same account every time.

  1. You will receive an email from "wikisupport@clicklaw.bc.ca" containing your username and password.
  2. Go to http://wiki.clicklaw.bc.ca/.
  3. Use the "Log in" button at the top right to log in with the username and password supplied in the email.
  4. Change your password to something secure that you will remember (if you need to find the Change Password page, it’s http://wiki.clicklaw.bc.ca/index.php?title=Special:ChangePassword).

Logging in to your new account.png

The "Edit" screen

Are you at the page you want to edit? Are you logged in? If yes, you can start editing.

  1. Click on the "Edit" tab or click on the "edit" link beside a particular section (if you only want to edit the text for a certain section of a page).

    Editing a page on the wiki.png

  2. You can make changes to the text in the edit window, and click on the “Save page” button to save your changes.

    Editing a page on the wiki 2.png

Basic editing tools and formatting

Clicklaw Wikibooks uses a simple markup language to control how content looks, but to start off, you don't need to know much about this markup language. Buttons along the top of the edit window frame do most of the formatting and wiki markup for you.

Editing tools explained.gif

Select a portion of text while in the edit screen, and then click one of the buttons to apply that formatting. The buttons have the following functions:

Bold

In the edit screen, selecting text then clicking button #1 will apply the wiki markup to make the text appear bold. Bold text is rarely called for by the Clicklaw Wikibooks Style Guide. Italics are preferred for giving emphasis. That said, it is sometimes appropriate to bold the first word in a list item. You can create bold text manually by enclosing one or more words in sets of three apostrophes. Typing:

I want to make '''this text''' bold.

Will look like this when you save or preview the page:

I want to make this text bold.

Italics

In the edit screen, selecting text then clicking button #2 will apply the wiki markup to make the text appear in italics. Use Italics sparingly to add emphasis to words that are unfamiliar or to disambiguate ones that the reader might mistake. Italics are used to cite cases, legislation or certain other sources. Consult the Clicklaw Wikibooks Style Guide for guidelines on when to use italics. To create italic text manually, enclose one or more words in sets of two apostrophes. Typing:

An ''arquebus'' is an early muzzle-loaded firearm, while an ''aquabus'' is a motorized boat.

Will look like this when you save or preview the page:

An arquebus is an early muzzle-loaded firearm, while an aquabus is a motorized boat.

Links

Internal Link

One page in a wiki often naturally leads to another page on the same wiki. For example, here is a link to the Clicklaw Wikibooks Style Guide, which is also useful because it tells you when bold and italics are used. To make an internal link click button #3. You will see [[Link title]]. Replace Link title with the exact name of the page (leaving the square brackets where they are) and you're done. Don't forget to hit "Save page." Typing:

Editors are encouraged to read the [[Clicklaw Wikibooks Style Guide]].

Will look like this when you save or preview the page:

Editors are encouraged to read the Clicklaw Wikibooks Style Guide.

Note: twin square brackets are used for internal links.

External Link

Examples of external links include any link to another website, or even a PDF or DOC file available somewhere online. Cases on CanLII, for instance, require external links. The simplest way to insert an external link is to just type the full URL, including the http:// prefix. Typing:

For more information on the Court of Appeal process, visit http://www.courtofappealbc.ca

Will look like this when you save or preview the page:

For more information on the Court of Appeal process, visit http://www.courtofappealbc.ca.

Much of the time, you won't want the link to appear so obvious. To have other words appear with links to online resources, select the text you want to contain the link, then click button #4. You will see

[http://www.example.com link title]

Replace www.example.com with the correct URL you want to send readers to (e.g.www.courtofappealbc.ca). Now replace link title with the words you want to contain the link (e.g.Court of Appeal BC Online Help Guide. Typing:

For more information, visit the Court of Appeal BC's [http://www.courtofappealbc.ca Online Help Guide].

Will look like this when you save or preview the page:

For more information, visit the Court of Appeal BC's Online Help Guide.

Headings and subheadings

Clicklaw Wikibook pages rely heavily on in page headings and subheadings to break up content and to improve navigation. Select the words that you want to become a heading, then click button #5. The results, when saved, will give you a primary section heading in the text of an article. Headings within a page can also be produced by typing multiple equal signs, and you are not restricted to a single, primary level of header. A primary section heading is written ==Words in heading==, a subsection below it is written ===Words in heading===, and so on (a maximum of five levels is possible). Spaces between the equal signs and the heading text are optional, and will not affect the way the heading is displayed. The heading must be typed on a separate line. Include one blank line above the heading, and optionally one blank line below it, for readability in the edit screen. (Only two or more consecutive blank lines will add more white space in the public appearance of the page.)

The following points apply to in page headings:

  • Use sentence case for section headings — that is, the initial letter of a title is capitalized; otherwise, capital letters are used only where they would be used in a normal sentence.
  • Headings should not normally contain links, especially where only part of a heading is linked.
  • Section and subsection headings should preferably be unique within a page; otherwise section links may lead to the wrong place.

Lists

The Clicklaw Wikibooks Style Guide calls for the use of bulleted lists to break up serial information where the order is not important, and numbered lists where steps or some other sequence is important to understand the information.

The edit toolbar does not have a button for making lists. They are simple to create, however. Authorities on plain language writing tend to agree that lists generally make information easier to absorb.

Making a list

Once you are logged in, and are in the Edit screen of the page you want to change:

  • Numbered lists: Place each list item on its own line, and start each line with a pound symbol "#". Click "Show preview" to see the list. Notice that the numbered list automatically ends at the last line that you started with a pound symbol.
  • Bulleted list: To make a list with bullets, follow the same steps as for a numbered list, but replace the pound symbol with an asterix.

List examples

Description This wiki code Results in this display on the page
Numbered list # One

# Two
# Three

  1. One
  2. Two
  3. Three
Bulleted list * Red

* Green
* Blue

  • Red
  • Green
  • Blue

More complicated lists with sublists are achieved by adding an extra pound or asterix symbol beside items you want to appear as indented subordinate list. Lists can include a subordinate list of another type, for example a numbered list can break off into a series of points in a bulleted list, or vice versa.

Description This wiki code Results in this display on the page
A numbered list with a subordinate list that is also numbered. # Item one

# Leads to item two:
## Which itself has at least one sub-item
## And possibly two
## Or even three sub-items
# Then back to the main numbered list and item three

  1. Item one
  2. Leads to item two:
    1. Which itself has at least one sub-item
    2. And possibly two
    3. Or even three sub-items
  3. Then back to the main numbered list and item three
A mixed list. Numbered list with a subordinate bulleted list. # Item one

# Leads to item two:
#* Which itself has at least one sub-item
#* And possibly two
#* Or even three sub-items which all need to be bullets
# Then back to the main list, which continues at item three

  1. Item one
  2. Leads to item two:
    • Which itself has at least one sub-item
    • And possibly two
    • Or even three sub-items which all need to be bullets
  3. Then back to the main list, which continues at item three
A bulleted list with a subordinate list of numbers,
and a further subordinate list of bullets.
* This point is simple.

* This point is complicated, and includes:
*# Item one
*# Item two, which is:
*#* 40% X,
*#* 35% Y, and
*#* 25% Z.
*# Item three
* This last point is simple again.

  • This point is simple.
  • This point is complicated, and includes:
    1. Item one
    2. Item two, which is:
      • 40% X,
      • 35% Y, and
      • 25% Z.
    3. Item three
  • This last point is simple again.


Images and video

Uploading images

To upload an image that you will use in a wikibook, or a contributor profile, select the "Upload file" link from the sidebar navigation menu. It is located under the "Toolbox" header.

Please restrict your photos to .png or .jpg formats.

Embedding images

There are several ways to embed an image — however only a couple work well in support PDF, EPUB, and print-on-demand viewing. Consistency is important, so please use the following approach: Writing this:

[[File:DescriptiveImageName.jpg| right | frame | link=| <span style="font-size:60%;">Copyright Information</span>]]</tt>

... should produce this:

Copyright Information

The copyright information may take the form of "Copyright www.shutterstock.com", for example.

Please use a descriptive name

Videos

Using the "Watchlist"

Account holders, including all editors and contributors, have the option of adding pages to a watchlist so they can follow content that they are responsible for and receive a notification when the pages are altered. You receive email notifications (see setting up email notificaiton) or be shown an overview of the changes from the Watchlist page.

Adding pages to watchlist

To add a page to your watchlist you must be logged in. From the page you wish to add, hover your cursor over the downward arrow beside the "History" tab, then click on "Watch." Adding a page to the watchlist.png

View your watchlist

Access the Watchlist from the top menu, or from the left menu. Once you are on the My Watchlist page, you should see a list of the recent changes from the last several days.

Viewing the watchlist.png

Edit your watchlist

Delete pages you no longer want to watch or receive notifications about. Check the box beside the name of the page you want to delete from the watchlist, then click "Remove titles". The pages will be deleted from the watchlist only, not from the wiki.

Changing the watchlist.png

Email notifications for watchlist

To enable email notification, which will let you know as soon as an edit is made to a page you watch, select "Preferences" from the top menu, select the "User profile" tab, then at the bottom under "E-mail options" select "E-mail me when a page or a file on my watchlist is changed." You can also control notifications about changes to your user talk page through this menu.

Email notification watchlist.png

Disabling Glossary/Terminology Popups

Terms that appear along with their definitions on the Terminology page will automatically be detected the first time they appear on any article in the Clicklaw Wiki. In general, this saves work, since no manual coding is required to ensure that a legal term will include a definition. The automatic nature of this process, however, will result in false-positives in cases where a defined term also has a common meaning in addition to a legal one (the terms "hearing", and "order" for example). To exclude defined terms from appearing with their pop-up definition (and where it is the first time the term has been used on a page), you should bracket the term with the HTML element:

 <span class="noglossary">term</span> 

A "div" tag will also work but create a separate paragraph that may not be desired. To exclude an entire article from receiving glossary popups, from the edit screen include the text:

__NOGLOSSARY__

at the end of the text of a page.

Plain language writing

A short definition of "Plain English"

Brian Garner, from Legal Writing in Plain English, 2001, pp xiv:

A word about "plain English." The phrase certainly shouldn't connote drab and dreary language. Actually, plain English is typically quite interesting to read. It's robust and direct—the opposite of gaudy, pretentious language. You achieve plain English when you use the simplest, most straightforward way of expressing an idea. You can still choose interesting words. But you'll avoid fancy ones that have everyday replacements meaning precisely the same thing.

Plain language tips

We are writing with the public reader in mind, not lawyers or other legal advocates. Depending on the wikibook, you may need to aim for a very low reading level. For example, Legal Help for British Columbians serves very basic information so people can take the first step towards finding help for their common legal problem. JP Boyd on Family Law, on the other hand, presumes a higher reading level, since it offers motivated self-represented individuals a slightly more detailed description of family law. Both groups of readers benefit from plain language writing methods. Some tips to consider when writing or reviewing legal information for the public:

  1. Think about your reader and question what they know or don't know.
  2. Think about questions your readers will have on the topic, and organize your thoughts accordingly.
  3. Summarize main points using headers.
  4. Organize steps or similar information with lists.
  5. Write brief sentences and keep paragraphs short.
  6. Use common phrases and words.
  7. Avoid unnecessary descriptive adverbs and words.
  8. Write in the active voice and keep verb and subject close together.
  9. Ask another reader to evaluate your writing.

More on plain language writing

Additional resources

The Clicklaw Wikibooks Style Guide highlights key style and word usage for pages on Clicklaw Wikibooks.

The MediaWiki website also includes excellent support material — for example, instructions on navigating a wiki, editing pages, and much more. (MediaWiki is free, open source software that powers Clicklaw Wikibooks, as well as the hugely popular Wikipedia.)

Note about updating resources in Legal Help for British Columbians

For contributors updating resources for the guide Legal Help for British Columbians, please see the explanatory note on the Resource List for Legal Help for British Columbians. (Resources are managed as individual pages that are then automatically consolidated on a single Resource List.)

For further information

This Guide is maintained by the Clicklaw site editors. For more information or support, please contact wikisupport@clicklaw.bc.ca.