Style Guide

In this guide, you will be introduced to the main style requirements GoTrained tutorial authors are required to follow.

Post Creation and Saving

To create a new post, go to the left sidebar > Posts, and select “Add New”.

To save what you wrote, please use the “Save Draft” button not “Publish” button.

 

Tutorial Structure

One of the first 3 paragraphs of your tutorial should start with “In this tutorial, you will learn…” explaining what this tutorial is about.

Our tutorials are mainly project-based tutorials, which means they are NOT about explaining every feature in a specific library or API, but they are rather about having a task that might be requested by a customer and explaining how to achieve it. For a clearer vision of what this means, please check our previous Python tutorials.

Move step by step, from creating any needed accounts or getting an API key to installing the required libraries and tools, importing your libraries and using them, and until you cover your whole project.

In the library installation section, mention the supported Python versions and any other technical specifications the reader should take into consideration. Mention also that you might need to start with sudo on Linux or Mac.

Readers might have different operating systems. So if you are using Terminal for any purpose, refer to it as “Terminal / Command Prompt”. If you are mentioning shortcuts, make sure you mention their equivalents on Linux/Mac/Windows.

Do not jump into using something you did not explain earlier. Our tutorials expect readers to have an intermediate level of Python, but that they never used the technology explained in the tutorial before. Still, if you are working on a series of tutorials, you may refer to a previous tutorial and add its link.

Dedicate the last section to Final Code including the whole working code of the tutorial.

Add comments to your Final Code to quickly explain what each part does.

 

Code Highlighting

When you add a new post, you will notice on the top toolbar, there is an icon like this <>

To mark some text as code, highlight the code line(s), click the <> icon, and click “Add”. That is it!

If you rather need to highlight just a word in between a sentence, mark the option “Inline” to the top after clicking <>

Otherwise, for a whole code of a line or several lines, just “Add” is enough.

 

Image Adding

You might need to add images to illustrate some steps.

Before uploading images:

  • Corp the image to remove unnecessary white margins. Otherwise, the image will look too small for the reader, and its file size will be unnecessarily big.
  • Rename the image file to reflect what it is about (e.g. “Telegram-Login.png”); this is useful for SEO.
  • PNG images are preferable if possible.

 

To add the image to your post:

  • Click the button called “Add Media” at the top of the page,  just above the formatting bar.
  • Then click the tab called “Upload Files”. Just drag and drop images or click “Select Files”.

  • Make sure the image is selected, and from the drop-down menu Alignment, select “Center”, and from the drop-down menu “Link To”, select “Attachment Page”; this will automatically make the image clickable so that the reader will be able to display it.

 

  • Finally, click the blue button called “Insert into the post”.

 

Section Formatting

To make the Table of Contents work fine, all what you have to do is to format each section title as “Heading 2” and Bold from the formatting toolbar, and if you have a subtitle, you format it as “Heading 3” and Bold. Do NOT use “Heading 1” at all.

Use the Title Case, i.e. make the first letter of each word is capital except: articles (a, an, the), coordinating conjunctions (and, but, for), and short (less than 5 letters) prepositions (at, by, from).

After the introduction and before the first title, “Insert Read More Tag” using the relevant toolbar button.

 

Linguistic Matters

Avoid spelling mistakes; install a spelling checker into your browser.

Do not use “We”; use “You” and the Imperative Mood whenever applicable; write “install the library”, not “we install the library“.

Do not use the Passive Voice; use the Active Voice as much as possible; write “do so and so“, not “something is done”. You can use the Passive Voice only when it does not refer to the reader.

Do not use spoken forms; write “you are” not “you’re ” and “cannot” not “can’t”.

Do not use the words “below” or “above” or any word that indicates physical location; instead you can use “here”, “as follows“, “previous”, etc. The problem with “below” or “above” is that if you change the article to another format like a book or video, or even if you change the navigation style of the blog, the mentioned part will be no longer “below” or “above”.

 

If you have questions, just please let us know.

 

Thanks for your efforts!

GoTrained Content Development Team

 

Rating: 5.0/5. From 1 vote.
Please wait...