guidelines

for creating awesome stuff at GitAll

In order for you to maximize your efforts and add value to it, we’ve created the following guidelines for your tutorials and write-ups. We hope this helps you overcome certain dilemmas during your process.

Please remember that these are just our recommendations and hence, not in any way, mandatory or musts to adhere to.

Research your Topic

Before you begin to write your outline, you should first research your subject to make sure you have a deep understanding of it.

Here are the sorts of things you should do during the research phase:

1. Check the official docs: Check out the official documentation/sample projects on your topic.
2. See how it’s used: Review open source software and popular apps using technologies related to your topic, to see how it is used in practice.
3. Find common questions: Search on StackOverflow to see what common questions are related to your subject, and ask developers you know what they’d like to learn in your tutorial.
4. Play around: Play around with some code demos to try out things related to your topic – consider this throwaway code, just for testing.
5. Result oriented writeup: It works better if you pursue a result with your write-up while demonstrating a technology. Instead of writing about scraping, for example, it works better if you take a use case or a problem and solve it using the technology. This keeps the user engaged, interested and usually is fun.

Define your Target Audience

Your tutorial should target a particular segment of users, specifically -

1. Beginners : assume that the user is completely new to the topic and you should try to explain each and every aspect in as much details as possible.
2. Intermediate: assume that your users are familiar with the technology, therefore only explain the new key elements that the user is expected to see for the first time.
3. Advanced: pretty self-explanatory, tutorials written for advanced user should contain in-depth explanation of “why” in addition of the “how”. Therefore, your Overview and Introduction of the tutorial should mention your target audience. For eg: “Intermediate approach. OpenCV installation on Ubuntu using Shell Script”

NOTE: Do not mention this in your Title. For example - “Face Detection with OpenCV [Intermediate]”. We’re working on adding it as a permanent field to our Tutorials and other writeup types.

Tutorial Format

Your tutorial should cover these important segments in the given order:

1. ELI5: Explain Like I’m Five. This section explains in simpler and lesser words the intent and features of your writeup. This is meant to help your audience decide if they’d want to go ahead with your tutorial. Refrain from adding click-bait content to this section. Rather, help your reader in realizing what they’ll learn out of your writeup.

2. Introduction: Write a little bit about the intention of writing this tutorial. Was it inspiration, or some problem you faced to which you spent hours finding a reasonable solution. Also given the user an idea of what will the final result will look like.

3. Prerequisites: Mention any preparations that have to be done by the user to completely follow the tutorial.

4. Content [rename this accordingly]:

• Theory - write about the problem that you are addressing a solution for this tutorial. For example, if you’re writing a tutorial about “Face Detection with OpenCV”, write about the mathematical concepts that are used in detecting a face in an image represented as a matrix.
• Code - provide step by step instructions of how to add the code, so that the reader can easily understand the steps, make use the inbuilt ‘code’ tag to improve formatting.
• Media - try to provide relevant media along with steps in the form of images or GIFs.

5. Conclusion - finally provide a reasonable conclusion, along with a summary of what the tutorial was about. This is also a good chance to provide links to additional resources that would be relevant to the reader.

Follow the Good Coding Convention

Whatever language you choose for your project, make sure to use proper coding conventions of that language. For eg, below are few universal coding good practices:

1. Variable, class and function names should always relay the intent of your code.
2. Use comments as often as possible.
3. Indent your code properly.
4. Classes’ names initiate with capital letters and are written using CamelCase. While, variable and function names, usually, start with lowercase letters and separated with underscore, appropriately named snake_case.

Every language has such coding conventions. Although you can’t always strictly follow them, it however makes your code readable and understandable by others.

This wraps up for Guidelines for creating original content on GitAll. If you have something to add to the above given recommendation, feel free to send us a PR or reach out to us directly at [email protected]