Contributing Guidelines

These guidelines are intended to:

• Help explanations have the same general style. I'm not picky about grammar, dw
• Make sure that people can read explanations well
• Tell you about advanced features & how to use them
• Ensure that explanations use non-discouraging language

Of course, you're not beholden to them. There are some things that I'll enforce (which will all be noted), but the vast majority is up to you. I trust you <3

Style

Alice & Bob

If you need example names for an explanation or for code (e.g. 'the Student object is named x'), please use these (in no particular order):

• Alice
• Bob
• Carol
• Danny
• Otis
• Sam
• Quin
• Elle

Grammar

Just... generally make sure that people can read it. You don't have to adhere to any standard :)

Demeaning & Discouraging Language

Some words will nearly always be read as patronising or confusing. Implying that an assignment is 'simple' or 'basic' when someone has been having trouble is incredibly discouraging for them. Please do not use these thoughtlessly.

If you have a usage, please read it through to make sure. These words aren't bad; they're just used a lot. I trust you to use them well.

• "Just"

  As in, "just print out the array". That implies it's easy, when it might not be easy for some people. Either remove it, or make it more clear using 'only' ("This assignment only wants you to print out the array").

• "Only"

  Depending on context, this can imply the same things as 'just'. Please make sure that your context is closer to 'Singly; alone; only; without another' than it is to 'easily; without difficulty'. It may not be 'without difficulty' for someone reading, and they may be discouraged if it is.

• "Basically"

  It may not be 'basic' for your reader.

• "Easily"

  It may not be 'easy' for your reader.

• "Of course"

  It might not be self-evident for your reader.

Advanced Features

Markdown!!!

Want formatting in your annotations? You can use Markdown! It's just like the formatting that Discord and Reddit use. For more detail, see this cheat sheet

HTML!

If you want to embed HTML into your annotations for more control, you can do that. However, the list of tags available is severely limited.

When using any illegal elements, your annotations will be rejected by the preview system and trimmed when published.

Globally allowed styles

You can style elements with CSS.

CSS styles may only be applied by putting them in the style property.

Some elements have other styles allowed too! See below for all allowed elements.

Allowed elements