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”.

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 the 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

As for how to add images if needed, at the top of the page, just above the formatting bar, click the button called “Add Media”. Then click the tab called “Upload Files”. Just drag and drop images or click “Select Files”. Then after the file finishes uploading, select a specific image, and then 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” from the formatting toolbar, and if you have a subtitle, you format it as “Heading 3”. Do NOT use “Heading 1” at all.

 

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 long “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...