Authoring guidelines

Here are some guidelines for creating good quality content.

Markdown

The best way to author content is using markdown. It is extremely easy to write content that renders very nicely and without having to fiddle with HTML. You can embed HTML snippets into a markdown as well where you need full control.

We have a Cheat Sheet project that you can use to see the full capabilities. To fork this starter pack into your own account, please click here. You should select the Use Pack option to create the project.

Courses and Books

We strongly recommend that when you are creating content at scale then you have a thorough understanding of the differences between projects, course units and books.

Media assets

When creating a book or a guide, you will often be working with images, video and other media. We recommend the following.

  • Images should be placed in the .guides/img folder. You can create sub-folders for organizational purposes.
  • Videos should be hosted on a 3rd party platform such as YouTube or Vimeo. You can embed these using regular HTML embed tags as available from those platforms.
  • Web based media such as Google Doc documents can be embedded using regular HTML embed tags as available from those platforms.

Callout blocks

Our markdown support the use of special callout blocks. These provide icons and highlighted backgrounds for various concepts such as : Important, Info, Challenge, Topic, Definition, Meetups, Headline, Hackathon, Create, Calendar, Growth Hack, Debugging, Cross Discipline and more.

Please refer to the Callout section of the Books Cheat Sheet. If you have not done so already, fork this starter pack into your own account. You should select the Use Pack option to create the project.

Don’t make pages too long

Again, this depends on your intended audience but try to keep each page reasonably brief. If the topic is a long one, you may want to break it up into several pages. This prevents lots of scrolling and allows students to digest information in manageable chunks.

Hidden folders

Your content will often want to show code samples. Codio’s recommended approach is to put each set of code samples into a dedicated folder. Then, using the page settings, you can specify this folder with the consequence that all non-specified folders are hidden from view in the file tree (if you choose to show it).

The benefit of hiding folders is that the student is not distracted by folders and files that are not relevant to the topic you are explaining.

Click here for more details on folder hiding.

Assessments

Codio offers a range of manually and auto-graded assessments. When used as a part of content, assessments are a very important way of giving students challenges and exercises that help internalize what they have been learning.

When used in a class situation, assessments are extremely helpful to the teacher as all assessment results are fed automatically through to the teacher class dashboard, allowing them to monitor students’ progress across a Course.

Many of Codio’s assessment types (code tests, multiple choice questions, text, fill in the blank and list-based) are auto-graded, saving teachers considerable amounts of time and can also offer students instant feedback on the correct answers.

You can also use the free-text assessment type for answers that require a typed answer that can be manually graded by faculty. The free text type also support Latex, so math questions can be answered and graded.

Layouts

The editor lets you create different panel layouts for your guide content and the layout can change from section to section.

Click here for more information on panel layouts.