This is a brief overview of how you should approach writing an article for the Discord Moderator Academy syllabus.
First of all - thank you for contributing! The contributions to DMA have come almost entirely from the community, which gives us the broadest set of experience and knowledge we could hope for.
This document is a set of guidelines and standards, not a set of rules. The most important thing to consider is what you want the reader to take away from your article, and so sometimes you may not follow the rules to the letter - and thats okay. The best advice I can give you is to ask questions. Asking for help - whether to proofread a finished submission, or to help you brainstorm your outline - isn’t a sign of weakness, it shows a commendable desire to collaborate.
The second most important thing is that these guidelines are not set in stone. If we’ve missed something, or made a mistake, tell us and we’ll improve where necessary.
The DMA syllabus will eventually be made available to anyone, and is intended for everyone who is interested in creating and maintaining a Discord community.
This may seem like a fairly simple statement, but it contains two very important things to keep in mind while writing your article.
The DMA syllabus should be accessible to anyone who wants to learn about maintaining a community on Discord. This means:
-
The language used should be in clear, plain English.
- For less complex articles (100-200), try to stick to words everyone will understand - especially someone who’s native language isn’t English. You can use tools like XKCD’s Simplewriter (https://xkcd.com/simplewriter/) to ensure you use language only found in the 1,000 most common English words.
- For the more complex articles (300 onwards), you'll have to use more precise language. It's always good to explain terms you introduce, or include a glossary
- The use of acronyms or technical language obscures meaning for someone less technically minded.
-
The language used should be open and inclusive.
- Obviously there is no place for racist, sexist, or otherwise derogatory language, but inclusivity can extend beyond that.
- Colloquial expressions and idioms might be harder for an international audience to grasp.
- Words may have meanings far beyond those apparent to you. Words like “blacklist/whitelist” or “master/slave” might be completely normal to a technical audience, but can carry drastically different meanings for other audiences.
The DMA syllabus isn’t just designed to give someone the technical knowledge about using the Discord client - its intent is to provide an education about every aspect of community moderation. Someone should be able to take the non-technical content of the DMA syllabus and apply it to any platform, be it Reddit, Twitch, or Slack.
- When writing a non-technical article (such as “how to write server guidelines” or “how to evaluate a ban appeal”) avoid relying too heavily on anything specific to the Discord client or service. Your article will of course be in the frame of reference of the Discord client and service, but the information should be relatively easily applied to other platforms.
- When writing a technical article (such as “how to set up a verification channel” or “how to understand your Server Insights”), feel free to focus just on the Discord client and platform. Where appropriate, use clear and annotated screenshots, taking care not to reveal any personal information, usernames, or discrims.
Now that we know what the goal of the article is, we can take a look at the language we should be using.
We want our articles to be engaging and approachable. This means its important to strike a good balance between using overly formal language, making the article seem cold and clinical, and using too much slang or informal language, which might hide the meaning of the article. One of the best ways to achieve this is use language you’d actually use when talking aloud:
- Use help instead of assistance
- Use let instead of enable
- Use but instead of however
- Use ask instead of request
Again, none of this language slips into using slang or metaphors, but it keeps the article more engaging, and reminds the reader that a real human being wrote it.
Another element of the article’s tone to consider is the use of nouns rather than their verbs. Nouns are naming words, like “decision” or “analysis”, and verbs are action words, like “decide” or “analyse”. When writing, there is a tendency to use far more nouns than we would in every day speech, and its best to avoid this:
- Use “we decided to” instead of “we made a decision to”
- Use “we analysed” instead of “we conducted an analysis of”
The difference between these styles of writing is often which voice the language is in: either the “passive” or “active” voice.
- Passive voice: “A message has been sent to you”
- Active voice: “We’ve messaged you”
Again, the difference between these two phrases is that the active voice uses a verb, whereas the passive voice uses a noun
Sometimes the difference isn’t so clear, so theres a very handy - and memorable - way of determining what voice a phrase is written in - monkeys! If you add “... by monkeys” to the end of a phrase, and it still makes sense, that phrase is passive:
- This bug will be fixed in the next update... by monkeys.
- Your ticket will be escalated to Trust and Safety... by monkeys.
If you do the same with the active versions of these phrases, it makes no sense:
- We’ll fix this bug in the next update... by monkeys.
- We’ll escalate this ticket to Trust and Safety... by monkeys.
These phrases don’t really make sense with “... by monkeys”, so they are in the active voice. You should try to use the active voice as much as possible.
To keep the reader engaged, the last thing to consider is the length of your sentences. Shorter sentences are easier to read for everyone, not just those who struggle with reading. Once a sentence reaches around 20 words, studies have shown that the number of readers who fully understand the sentence drops off quickly. Try to keep your sentences around 14 words in length, but don’t be afraid to use some more complex sentence structures. The best advice here is to read your sentence aloud - if you are running out of breath, consider adding a comma, hyphen, or parentheses. If that doesn’t help, find a way to break the sentence in two.
Formatting is much more of a technical aspect of your document, but it is important nonetheless.
Using headings in your document really helps its readability, and prevents it from being just one massive block of text. Try to make your headings, subheadings, and sub-subheadings act as labels or short summaries for the paragraphs below it, acting as a short summary. You should be able to scroll down the sidebar of all the headings and get a fairly good overview of what the article is about.
Using a headings structure also really helps in writing your document. When you first sit down to write, a blank page may feel a little daunting. If you jump right in and start writing out paragraphs, you may find yourself lost, or end up going off-topic. The best thing to do when writing an article is to have an outline of your headings first. This helps you stay on-topic for the whole article, and helps avoid going over the same topic in multiple different sections.
The last thing to consider with formatting is the technical limitations of the medium. These are minor points, but still worth considering:
- Don’t rely solely on bolding or italicising your text, as screen-readers may ignore formatting.
- Some users may not have emoji installed on their device, so it’s best to avoid using emoji where you don’t have to
- Images are extremely useful, but again - don’t rely on them. Each image should supplement the content of the page, not be the content its self.
Each article in the DMA curriculum has its own numerical label, which is constructed of two axes. The first number indicates the complexity of the article - the 1xx series covers the absolute basics, whereas the 5xx series are advanced “grad school” classes. This complexity scale is extremely important to remember. It’s also worthwhile noting the latter two numbers, but these usually relate directly to the topic at hand:
- 00-10 are for foundational understanding.
- 11-20 are for the human aspects of moderation.
- 21-30 are for bots, automation, and AI.
- 31-40 are for community management and growth.
- 41-99 are for other advanced or miscellaneous topics.
Here’s a detailed breakdown of what we expect from each complexity level of the curriculum:
- 1xx Series
- These articles cover the absolute basics, and should be aimed at absolute beginners - maybe they don’t even have a Discord account yet!
- These articles should act as a “how-to” guide for the basics: which buttons to press, which button does what, and what the immediate consequences of pressing the buttons are.
- Readers of these articles may have little to no experience with Discord as a platform, so it’s good to make the articles as straightforward as possible. You could try asking a friend or family member who doesn’t use Discord to read through the article and ask if they understand it.
- A 1xx article should be around 1-3 pages of A4/Letter.
- 2xx Series
- These articles begin to get a little more in-depth, but are still very much beginner articles.
- Once a reader has completed the 2xx series, they should have a solid foundation for using Discord, and be able to create a functioning - albeit very bear-bones - Discord server.
- Where a 1xx article told readers which buttons to press, a 2xx article should justify why they are pressing those buttons, and go into a little bit of detail about the consequences.
- A 2xx article should be around 2-5 pages of A4/Letter.
- 3xx Series
- These articles should go into depth about their topic, covering all aspects of how to moderate a stable community on Discord.
- Once a reader has completed the 3xx series, they should have the tools and skills to maintain a reasonably large community, and take full advantage of all the tools Discord provides - both native and with Bots.
- The language used in these articles can also begin to become more specific - referring to “Guilds” rather than “servers”, for an example.
- A 3xx article might be around 3-7 pages of A4/Letter.
- 4xx Series
- These articles should take deep dives into their topic. Many moderators of reasonably large servers may never need to read a 4xx article.
- Readers may also begin to pick and choose which 4xx article they read, as some may never be relevant for their community, so try not to rely too heavily on cross-referencing other 4xx articles.
- These articles should also begin to be geared towards community owners or administrators, not just rank-and-file moderators.
- A 4xx article might be more than around 4 pages of A4/Letter.
- 5xx Series
- These articles are the “grad school” of community moderation. If you are reading these, you are probably more interested in the overarching philosophy and strategy of a community, looking at long-term growth into the hundreds of thousands.
- These articles may border on what professionals use in their day-to-day jobs, so don’t tackle one of these articles head-on if you aren’t confident with that level of detail.
- A 5xx article shouldn’t be more than around 10-15 pages of A4/Letter
One of the most important considerations with the complexity of your article, especially for the 1xx and 2xx series, is to avoid going into too much detail. It may sound counter-intuitive, but loading up a 2xx article with pages and pages of information isn’t helpful - it only makes the article hard to read. Don’t be afraid to talk to the author of a more or less complex equivalent of your article, and work out which points should be included in which.
Additionally, the suggestions for page length here really are suggestions. They all rely on font size, formatting, and the use of images, so don’t be afraid to ask someone for help about your article’s length.
By now you should have a good grasp on what is expected from a DMA article, in terms of content and language. As mentioned at the beginning, however, these aren’t rules you have to follow to the letter. Language will always be subjective, and the best tool you have is asking for help.
That being said, there are some ground rules. As these articles are written, essentially, on behalf of Discord, there’s some important considerations:
- While you can make a list of suggestions, such as moderation bots to use, don’t highlight any in particular, as that would be seen as a commercial endorsement.
- It’s an excellent idea to read around the topic - a lot of the tone-of-voice guidance here was inspired by Monzo’s own Tone of Voice guidelines (found at https://monzo.com/tone-of-voice/), and you’ll see I’ve used their examples, but none of the content was directly plagiarized (copied). Where possible, it’s best to take inspiration from work that is in the public domain.
This document serves as a comprehensive guideline for writing a clear and precise article for the DMA syllabus. It’s quite long, but if you take anything away from it, it’s these three things:
- Ensure your article uses plain and simple English, without technical vocabulary or abbreviations.
- Keep your content on-message, within its complexity scale, and applicable to any platform (where appropriate / non-technical).
- Ask for help! Once you’ve written something down, it’s incredibly hard to spot a tiny mistake, so asking someone to proofread your work regularly is your most powerful tool.
Written by ash#0001 on behalf of the Discord Moderator Academy