Text-Based Content¶

This section offers guidelines and tips for creating text-based lessons, tutorials, and blog posts for CodingNomads. This information can also help you to improve your technical writing skills.

After reading this article, you'll know how to:

Structure your articles to make them impactful
Format your text for increased readability
Use the right tone to address your audience

Following these guidelines is important to achieve consistency and high quality in the technical writing that CodingNomads wants to offer to our students. Please read over these tips carefully and implement them in your writing.

Structure¶

This first section will guide you in structuring your technical writing so you can improve its readability and help readers to learn better from your content.

Three-Step Principle¶

Follow the three-step-teaching principle: Many have recommended to use this structure, and we do too:

Intro: Tell your students what information you will give them
Main: Give them that info
Recap: Tell them what information they just got

Follow these three steps even for short sections in your writing. Our brains process new information in small chunks, and they need a proper introduction and recap to fully absorb new topics.

Assume that your students are new to everything you're teaching them. Following the outlined steps above helps them remember the content you're teaching. It makes learning more fun and effective for your students.

Introduction¶

Sell your article: Every lesson should start with a quick introduction. This is especially important for longer-form blog posts and tutorial articles. Your tutorials need to have a concise introduction that gives readers a good idea of what they will know to do after reading your text. Lists are a great tool for introductions. For example:

After reading this article, you'll know how to:

Structure your articles to make them impactful

Format your text for increased readability

Use the right tone to address your audience

Attention is fleeting in the online world. Think of your introduction as an advertisement for your article. Keep it concise and make it clear to your readers what they'll gain from committing to reading your text.

Conclusion¶

Recap your article: Your text should end with a quick recap of what students gained by reading over it. If you are writing a self-standing tutorial or blog post, this conclusion needs to have its own heading.

Many potential readers jump right to the conclusion of an article to decide whether they want to read it or not. Use it to recap the most important take-aways from your text. Make it actionable and focus on telling readers what they learned by reading your article. Use lists and focus on a similar form as you used for your introduction.

Sum-Up Paragraphs¶

Sum up paragraphs: Try to sum up the paragraph's entire content in the first sentence. You can think of it as a mini-intro and mini-conclusion all in one piece. The body of the paragraph that follows explains the concept in more detail and gives readers a chance to linger and absorb the information. This paragraph is an example of using this approach.

Parallel Structure¶

Use parallel structure for lists and headings: Clarity is important for technical writing. Always use parallel structure when creating list items as well as headings.

Parallel structure means to use the same sentence structure for each new piece of information. E.g. I wrote all the headings on this page as nouns. Each paragraph that introduces new information begins with a verb and attempts to convey the main idea of that paragraph.

Parallel structure is very powerful in making your content look well structured. It can help yourself to plan out a topic clearly, and it helps your students to easier absorb the information.

Flat Table Of Contents¶

Use a flat TOC structure: Aim to use main headings and only one additional level of sub-headings, not more.

If you are writing lessons for the learning platform, that means using <h3> headings as your main headings, and <h4> as sub-headings. If you're writing a blog post, use <h2> and <h3> headings.

Text Blocks¶

Use text blocks: Each paragraph should have a visible body to it. If a text contains multiple paragraphs that consist of only one or two sentences the text may appear less professional at first sight. No need to be too strict about this, but keep it in mind when creating your content. On the other hand, also avoid making your paragraphs too blocky.

Visual Aids¶

Use visual aids: Using graphs, code blocks, images, or even fun memes can help to lighten the information load on your readers. Technical content can get overwhelming. You're encouraged to loosen it up and give a break to your readers' eyes by introducing visual aids.

If a text section seems long and dry to yourself, it will also seems so to your students. Pop in some images to change the visual pace.

When you use visual aids, use the three-step-principle to introduce them, as well as to add a mini-recap.

Note Blocks¶

Use note blocks: You can use Note and Info blocks as visual aids as well as to highlight important information that might be a little aside of the main text.

If you write course content for the platform, then check out the description on Information and Alert Boxes. If you are writing a tutorial for the CodingNomads blog, then use Markdown quotes (>) instead.

Code Blocks¶

Explain code blocks: Code blocks can be a great addition to your technical lesson. Your readers are most likely beginner to intermediate programmers, therefore it is important that you explain the code you present to them.

If possible, then keep the code blocks short in order to highlight what readers should focus on. When you build a project, take small steps and show the changes to the code often to avoid too many changes at once.

If you show your readers a longer code block with multiple changes, then make sure to address and explain all the changes explicitly, preferably using a list.

Lists¶

Use lists wherever possible: Lists are a great tool for technical writing. When used correctly, they can serve both as a visual aid, and a concise presentation of content.

If you write about multiple examples, or introduce x ways of doing something, always opt for presenting this information as a list.

List & Paragraph Headings¶

Use list and paragraph headlines: Bolded words or short sentences at the beginning of a list item or a paragraph help to introduce a topic. They guide your students' eyes and assist in easier absorbing relevant information. Always try to keep them in parallel structure.

As an example, revisit the list further up that explains the three-step-principle.

Sentences In Brackets¶

Avoid sentences in brackets: Half-baked sentences in brackets are usually an indicator that you haven't thought enough about whether or not to include information in your text. The same holds true for sentences that are cut apart by em-dashes (--).

These sentence constructs are distracting in technical writing and should be avoided. If you notice one of these constructs in your text, take a moment to reconsider what it is you want to say. Then either add the sentence normally, or delete it.

Slashes Between Words¶

Avoid slashes between words: Another writing habit to swear off of for technical writing is using multiple words separated by slashes, e.g.:

❌ In this tutorial/blog post, you'll learn...

This breaks the reader's flow and creates more confusion than it resolves. Students come to technical tutorials for clear and concise information. If you notice that you are using slashed words, take a moment to consider what is the most accurate word to use. Then delete the others.

Words In Quotation Marks¶

Avoid words in quotation marks: Don't use words in quotation marks for technical writing. It is another example of introducing ambiguity to your text that has no place in technical writing.

If you notice you're putting a word into quotation marks, reconsider what it is you want to express. Usually there is a precise word for it. Use that instead.

Formatting¶

The following points provide guidance on how to format your technical writing for consistency and readability.

Consistency¶

Be consistent: Just like in programming, there are many correct ways of formatting your content. Please adhere to this style guide to allow consistency across all CodingNomads courses. And, most importantly, be consistent within your own course materials.

Bolding¶

Use bolding for new terms: Bolding should be used to introduce new terms and highlight key phrases:

✅ In this section, you'll learn about iteration.

Avoid bolding whole sentences in your text, unless they are paragraph headings. Bolding too many words at once reduces the visibility of the most important terms that you want to highlight.

Emphasis¶

Use emphasis to put focus on a word: Emphasis should be used to put emphasis on a word:

✅ There is so much to learn.

As with bolding, avoid putting emphasis at too many words at once.

In-Line Code¶

Format code: You're writing technical tutorials, so it is especially important that you're clear about what words refer to code, such as functions, methods, attributes, or code libraries. Use single backticks (`) in Markdown to correctly format your code. alt Generally, use the code you refer to as a noun in your sentence:

✅ With Python's print(), you can display output to your console.

Avoid adding the type of code structure you're talking about after each mention of it:

⚠️ With Python's print() function, you can display...

You can be explicit and use this construct if you are making a point about print() being a function, but avoid overusing it.

Numbers¶

Spell out numbers: When mentioning a number in your text, use the word for it instead of writing down the number:

✅ Below, you'll see three examples...

Using the word instead of the number itself tends to be perceived as more professional.

Links¶

Write text-based links: Avoid using words such as "click here" or just "link" to as the link text for external sources. Instead, make the link text a natural part of your sentence:

✅ Code comments can help your future self, as well as other programmers, to understand your code. Use descriptive variable names in combination with explanatory code comments, where code tells you how and comments tell you why. This is the most effective way to write user-friendly code.

If possible, use the title of the linked resource in your sentence. This makes your sentence more user-friendly to read and retain. Another example:

✅ If you are still new to Python, or you need a refresher, check out the Python Software Engineering course.

Using natural link texts makes your paragraphs better readable and immediately clarifies where the link will take them.

Tone¶

The following points give guidance on what to look out for in terms of tone and word choice when creating technical tutorials.

General Tone¶

Be friendly, supportive, and professional: Our students should feel that they are chatting with a knowledgeable and encouraging friend who is invested in their progress and also happens to be an expert on the subject matter.

'You' vs. 'We'¶

Use "you" instead of "we": Talking directly to your student makes them feel personally addressed and more engaged:

✅ The project you'll be working with...

Always talk directly to your readers. Imagine that you are writing your content for a specific person.

Hidden Plural¶

Some commonly used sentence constructs are a hidden use of 'we'. You should avoid them as well. For example, don't use "let's ...":

❌ Let's next learn how to ...

Instead, keep your focus on the reader and keep them in the center of attention:

✅ Next, you'll learn how to ...

Always talk directly to your readers. Imagine that you are talking to a specific person that is sitting in front of you.

Word Choice¶

Choose your words wisely: Avoid using words such as:

❌ "easy"
❌ "straightforward"
❌ "obvious" etc.

Your students are new to this topic, and what might seem easy to you, won't necessarily be easy for them. To avoid alienating students, rather use words such as ✅ "user-friendly".

Personality¶

Show your personality as an author: No one likes to read or watch a sterile tutorial when learning something new and challenging. Add your personal touches, whether that means using xkcd comics, memes, or dad jokes.

Of course only if that's how you roll. Don't force it, but feel free to make it fun both for yourself while writing, as well as for your students when reading your content. Most of all, allow yourself to be authentic instead of sterile.

Mistakes¶

Show the instructor is also a mere mortal: It helps students to know that you also make mistakes, and that also for you some concepts were daunting at first or difficult to grasp.

Support¶

Show that you're supportive: Programming topics are tough and often confusing for newcomers. Even after making some progress it can easily feel overwhelming when the door opens up wider and ever more information starts flooding in.

Try to help your students by giving them a stable ground to stand on. Be supportive and encourage them to keep learning.

Fun¶

Feel free to have some fun! We want your students to enjoy your content as much as possible and laugh as often as possible! :)

Images¶

Make sure to only use image material that is copyright-free. Here are a couple of resources where you can find free stock images:

Please add attribution, for example in alt texts, if that makes sense.