The guidelines ensure quality, guarantee a consistent learning experience on serlo.org and answer questions about the creation and editing of articles.

Of course, it is difficult to take all guidelines into consideration but don't worry, every contribution will be checked by experienced community members who will give you feedback. You are welcome to comment on a video, article or course if you have any questions.

These guidelines are not set in stone and we welcome any ideas or suggestions from you on how to improve them. Please post them as a comment on this page.

Headings

Every article and some courses are structured with hierarchical headings.

How to Organize Headings

In the editor, put ## in front of the first heading of a article, also called “h2”. The h1 heading is reserved for the title of the article.

Put ###, called “h3”, in front of the first heading a course. The h1 heading is meant for the title of the whole course and the h2 heading is reserved for the title of the course page.

Put one more hashtag in front of every successive heading. ####, #####, etc.

Headings and Layout.

To recognize the structure of h2 headings in articles (and h3 headings in course pages) in the editor, create a new layout for each heading.

It depends on the content and your own judgement, depending on the structure of the articcle, which layout you choose. You can find some tips about the arrangement of charts, diagrams and examples further below.

Link Headings

Never put direct links in the headings of articles or courses.

Highlights

  • You can link to terms that already have an article that is relevant within the context of the original article – one link after each big heading. Links are never written in bold or italics.

  • The most important terms in an article are written in bold as long as they are not also a link.

  • All “semi-important” terms (e.g. work steps, everything that you yourself deem important) can be written in italics.

Punctuation marks are not part of the highlights.

Formulas in the Text

All mathematical symbols (formulas, functions, parameters, variables, etc.) are written in the format "%%\%\%\;\%\% %%": %%f(x)=2x^2+1%% instead of f(x)=2x²-1.

Use the format %%\$\$\;\$\$%% When you want to write an important formula, that is seperate from the text:$$a2+b2=c2$$

You an find further details on the formatting of formulars on this page LINK

Placement of Images

There are several options for placing Images

  • They are placed on the left if they are the important element and the text is only meant to explain or describe the image.
  • They are placed on the right if they are meant to support or illustrate the text.

You can have images stretch across the whole page. Do this when the image if especially important to present crucial results or if it would be too small otherwise.

Tables

The most elegant way to create tables is with a layout with several columns.

Should you need more columns or if you want to have a grid then you can create a table or chart in the editor yourself. You can find a tutorial on creating tables on the help page for markdown

Example Exercises

Example exercises are useful in many articles with calculations. These are not part of the exercise section and are explained in detail.

To display these exercises properly you need a layout with more than one column. You write the method or approach in the left column and the related step of calculation in the right column. Also, every line of the equation should be put in a seperate line of the layout.

Caution: In the exercise section of serlo.org, the order is exactly opposite because the focus is on the exercise and not the method.

Abbreviations, Inserts and Lists

You don't have to write out everything in full. Common abbreviations like “e.g.” are allowed.

Please put a space before and after Inserts. You can use hyphens or brackets for inserts.

There are two kinds of lists in the editor. If you put an empty line between the elements of the list, they are spaced further apart. If you write them without an empty line they are displayed just like that.

Improving Clarity

Your article should be written concisely with a clear structure so that new contributors have it easier to work in the editor. Optimally you want the source text to be as close to the rendered text as possible. This is the ideal situation but not always achievable.

Try to avoid unnecessary empty lines, spaces and tab stops while still inserting enough paragraphs to improve the readability of the text.