My HP

Tutorial Guidelines

The aim of the HostPresto! Community knowledgebase is to provide extremely high quality tutorials on web hosting, web development and web applications. Each tutorial produced should be easy to follow, correctly formatted, and technically accurate. The tutorial should:

  • Not assume anything about the users existing knowledge of the subject.
  • Explain fully from start to finish the topic at hand, allowing a ‘smart user’ to complete the tutorial with the same results.
  • Not link to external tutorials – the tutorial should provide a complete resource in one place, rather than sending the user off to other mini tutorials.
  • Spell out each step with clear instructions, and provide additional detail where needed.
  • Stay within the scope of the subject. For example, if the tutorial is about a WordPress plugin, the tutorial can assume the user already has a working WordPress installation and is proficient in logging into the admin dashboard.
  • Grammatically correct and formatted correctly.

Structure

A tutorial (excluding multi part ‘series’ tutorials) should start with an Introduction (explaining what the tutorial is for and what by the end you should have achieved) and finish in a Conclusion (summarising what the reader has achieved and any additional notes).

An article should be structured so instructions and then examples are provided in alternating steps. For example:

To begin, log into your WordPress admin dashboard.

Go to Plugins in the left menu.

<< Screenshot / Command Example / Code Example >>

Click on the ‘Add New’ button

<< Screenshot / Command Example / Code Example >>

And so on…

Each step should be a single action, try not to combine multiple actions into one step. It may not be necessary to provide a screenshot or example with every step if it’s a common / obvious step. The tutorial should educate the user while they’re doing it, rather than providing a source for copying and pasting or blindly following – separating the steps and explaining clearly with additional information if required will help this. Steps should not be numbered.

The tutorials should not link to external tutorials – it should be self contained from start to finish. The tutorials can link to other HostPresto! tutorials to explain prerequisite tasks. If a tutorial for the prerequisite task does not exist, one should be created beforehand (following the same HostPresto! submission process).

The length of the tutorial is not as important as quality and completeness. Generally a tutorial can range between 1500 and 5000 words in length. We would much prefer you write multiple, high quality tutorials than filling out a single tutorial with ‘waffle’ just to get the word count up – you’ll still get paid the same (if not more), it will be much more fun to write and much better for the reader.

Person and Formality

Tutorials should use a friendly, fun but mildly formal tone. They should be clear and concise without ‘waffle’, providing a balance between useful and over detailed information – elaborating in places that require it is encouraged.

As this is a tutorial rather than a blog post, use of the first person singular should be avoided. For example, phrases such as ‘I think’, ‘I suggest’ or ‘I recommend’ should not be used, however it’s acceptable to use the first person plural (‘we’, ‘our’ etc), and the second person (‘you’, ‘your’ etc). This helps keep the tone of the article formal but friendly. For example:

Now that you have logged into your control panel.

We can see that the status has changed to complete.

Images

As a lot of the tutorials will involve graphical user interfaces (GUI) it’s expected a high number of screenshots will be required. Images should be no bigger than 800×600.

It’s important that screenshots are only used for GUIs and similar. In situations where you want to convey items such as configuration files, settings, or individual pieces of text (such as confirmation messages), screenshots should not be used. This is for two reasons; the first is because the user may want to copy and paste the configuration or setting. The second is that images take up a large amount of space on the screen which is overkill if you’re wanting to provide an example of a few lines of text.

Screenshots should be of the entire browser viewport (i.e, not any of the browser itself (no scrollbars, no menus, no tabs, no mouse pointer visible). The screenshot should not include too much ‘white space’, cropping empty spaces from the bottom/side of the screenshot is recommended.