Appearance

Writing a Challenge Description ​

The descriptions of the challenges are made by users, more precisely by the people who create the challenges. These descriptions are of massive importance because they not only define exactly the challenge and its requirements but also because they are the first interaction of the users with the challenge. For this reason, the descriptions must be clear and to the point, to provide all the information in a simple way that everyone can understand.

General ​

  • English is the language! The descriptions must be written in English. The DojoCode community is an international one, so if you don't speak English, you can ask for help with proofreading and spell-checking.
  • Every opinion matters! If there are complaints or remarks about the description of the challenges, they must be taken into account. We must take into account the fact that after working a lot on a challenge for yourself, the request and the solution may seem more familiar than to a user who sees it for the first time. For this reason, it is good to invite other users to take a look at the description, to see if they understand it and if what they have to do is clear and to the point.
  • Keep it simple! Your challenge may be translated into other programming languages. For this reason, it is good that the descriptions are written as language-agnostic as possible, and only abstract terms are used, not specific to a certain programming language. Since the description cannot be kept language-agnostic, language-specific elements should be structured in a way that helps with the resolution of merge conflicts, more precisely: in phrases or larger blocks. Multiple language concepts in a single sentence should be avoided.
  • Clean and clear! The description and requirements must be clear and easy to understand. For each user, this is the first step in choosing your challenge and understanding it.

Structure ​

The structure should be simple and each part should have a meaning.

For example:

  • The description must contain a sentence about the definition of the respective challenge followed by the requirements for the challenge.
  • Adding a picture to represent a preview of the solution to the problem.
  • A snippet with the output and/or input of the problem.
  • If you have, you can add additional notes, technical details, or follow-ups between the preview and the snippet with the output. But keep in mind not to add unnecessary details.
  • Videos or gifs are a good idea if you want to personalize your challenge more. We recommend using as much original content as possible, so you can add elements such as videos or gifs

The description must be short and precise. The secret is for the description to be short and easy to understand. It makes no sense to get lost in useless details because you risk the message getting lost. Try to answer 3 simple questions: What, Why, and How?

TIP

It's good to start with the important things first, use the upside-down pyramid idea. Start with the most important aspects and progressively leave the details that are not necessary for the end.

Requirements ​

The description should meet all the requirements that the creator expects from the user. You can also add some common mistakes that you think a user might make. Thus, if the user does not pass the verification tests, he can check the description to see if he does not find help.

  • Help but don't share everything! Snippets with output or input are very useful. However, it is recommended to let the user think as well, so be sure that you don't share too much.
  • We don't give up! Try to avoid expressions like "unlock the solution in case you can't handle it". Once a user unlocks a solution, he loses points and fails the challenge.
  • Words are the secret! It is very important to use pictures, they attract attention and help the user. However, do not use pictures for anything, the description and requirements are better to remain written in words. You can use the pictures to show the user a preview of the challenge.
  • Draw attention to the difficulty! It presents the situation from the beginning. Thus, it is good to highlight the complexity and difficulty of the challenge.

Formatting ​

You can use the markdown function to help you write a more organized description. You can add titles, subtitles, lists, tables and more. However, do not abuse it, too many styles for a relatively small text can be too loaded.

  • Use the correct headings! Don't use #Title to insert sentences, instead, you can use ## Second level or ### Third level headers.
  • Quality pictures! For pictures, you can use certain special programs, so that the quality is good and the image is clear.
  • Simple and beautiful! Avoid descriptions where you mention many coding languages. Using multiple coding languages ​​in a single paragraph can be too loaded and lose the user's attention.

Other ​

  • You can add if you consider it necessary, external links or references. This is not mandatory, but in some cases to help the user you can do this.
  • The descriptions must contain all sources of information. So if you used another challenge for inspiration or another website, you must mention that in the description.