Skip to content or footer

Articles - Formatting

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.

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)=2x2+1f(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:

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

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.


This content is licensed under
CC BY-SA 4.0Info