Style Guide

From Coder Merlin
Revision as of 20:44, 1 February 2022 by Jeff-strong (talk | contribs) (→‎Writing Style: added ly- vs ly rule)
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[edit]

  • 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[edit]

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[edit]

Emphasizing Important Concepts in the Main Text[edit]

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

General[edit]

Pathname

Glossary[edit]

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[edit]

Inline Bash Command

Quotes[edit]

Blockquote Line 1
Blockquote Line 2
Blockquote Line 3

— Famous Person

Swift[edit]

Swift Class

Swift Identifier

Swift Keyword

Swift Library

Swift String

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

General Experience Flow[edit]

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

Ideas / Coming Soon Box[edit]

ComingSoonIcon.png
Coming Soon
  • Describe what is coming soon

Merlin Boxes[edit]

Hint.pngHelpful Hint
Helpful Hint


Best PracticeHintIcon.png
👍 #Best Practice

Do this!


CautionWarnIcon.png

Be careful!


Key ConceptsKeyConceptsIcon.png
  • First concept
  • Second concept
  • Third concept


ObserveObserveIcon.png
Observe, Ponder, and Journal: : Section 1
  1. What did you observe?


ExercisesExercisesIcon.png
  1. First
  2. Second
  3. Third


Going DeeperGoingDeeperIcon.png
  • Detail 1
  • Detail 2
  • Detail 3

Program Boxes[edit]

New document
Create a new project


Start button green arrow
Run the program.


Stop button red ex
Stop the running program.

Multipage Experiences[edit]

  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.