Style Guide

Within these castle walls be forged Mavens of Computer Science ...

— Merlin, The Coder

This page documents writing style and standard markup for this wiki.

General Rules

• Ensure a consistent style based on the articles written before you and the template below.
• All images must be original works or obtained from https://commons.wikimedia.org.

Writing Style

Purpose. As an author for Coder Merlin, you are writing to instruct, not to impress people with how much you know or how large your vocabulary is. Write simply.

Audience. Keep in mind that you are writing for high school students (the typical reader). Try for a reading grade level of around 10th grade. To see if you’re on the right path, you can take a paragraph of your writing and analyze it for the Flesch-Kincaid Grade reading level.

To keep the writing simple, use short sentences, choose simple words, and write in active voice.

Use the second person point of view and active voice. "You can learn coding by following the lessons in Coder Merlin." That sentence in passive voice is: "Coding can be learned by following..."

Use imperative sentences for short commands or requests.

When writing for Coder Merlin, use the Given–New principle. Help people learn by expressing known information (the given) before previously unknown information (the new) in your writing. This puts the idea in context of something they know and can relate the new information back to it.

Be friendly, encourage students to be inquisitive.

Use the serial comma.

Word and phrase choices

Preferred words and phrases

Instead of...	Use...
in order to	to
in order for	for
utilize	use
ly-	ly (no hyphen should be used after a word ending in "ly ")
currently	avoid unless comparing to another time frame
may	could, can, or might (use may only when meaning that something is permitted)
locate	omitting rarely changes the meaning, unless you’re using it as to find something

Syntax Highlighting

Emphasizing Important Concepts in the Main Text

• Use italics to emphasize important concepts in the main text.
• Use a glossary reference for new terms, e.g., Boolean

General

Pathname

Glossary

Newly defined terms (or terms with a specific meaning within Computer Science) should be placed in the glossary as follows:

On the Glossary page, find the correct section for the term, based on the first letter of the term, and edit the section. Add a new term by using the following line of code:

{{GlossaryItem|anchor|word as it appears in the glossary listing|definition of Glossary Item}}

The anchor is case-sensitive and can be a word (i.e., Array) or a phrase (i.e., Abstract Data Type) and must be a unique key within the entire glossary. Currently, glossary items that are phrases use an anchor that is in Title Case, with each word in the phrase separated by a single space character. Most often, using the word or phrase itself is sufficient, but this may be easily verified by going to the Glossary page. The anchor is the identifier used by a Glossary Reference to find the correct Glossary Item.

On the page in which the new term appears:

{{GlossaryReference|anchor|word or phrase that will link to the Glossary Item}}

Inline Bash Command

Inline Bash Command

Quotes

Blockquote Line 1
Blockquote Line 2
Blockquote Line 3

— Famous Person

Swift

Swift Class

Swift Identifier

Swift Keyword

Swift Library

Swift String

// This is a Swift Code Block
print("Hello World!")

General Experience Flow

(image on right)
== Prerequisites ==
== Background ==
(Use when required for background reading)
== Introduction ==
== Topic Headers ==
== Key Concepts ==
== Exercises ==
== References ==

Ideas / Coming Soon Box

	Coming Soon
	Describe what is coming soon

Merlin Boxes

Helpful Hint

Helpful Hint

Best Practice

👍 #Best Practice

Do this!

Caution

Be careful!

Key Concepts

• First concept
• Second concept
• Third concept

Observe

Observe, Ponder, and Journal: : Section 1

1. What did you observe?

Exercises

1. First
2. Second
3. Third

Going Deeper

• Detail 1
• Detail 2
• Detail 3

Program Boxes

Create a new project

Run the program.

Stop the running program.

Multipage Experiences

1. Complete the experience on a single page, as usual.
2. Place a "Sequenced subpages" property on the original single page article, which lists each of the subpages, in order, delimited by semicolons, i.e., { {#set:Sequenced subpages=Client and Server;First Connection;Terminating a Partial Command} }
3. For each subsection of the article (i.e., a section beginning with two equal signs), create a same-named subpage and MOVE the contents from the subsection onto the subpage. Do not change the subsection names or remove the heading with the two equal signs.
4. Place the template MerlinMultipageExperience on the original single-page article.
5. Place the template MerlinMultipageExperienceNavBar at the bottom of the original single-page article.
6. Place the template MerlinMultipageExperienceNavBar at the bottom of each SUBPAGE contained within noinclude tags.
7. Create another SUBPAGE titled "All" and place the template MerlinMultipageExperienceAll on this page.