Tips for writing an effective tutorial

After having written so many of these, I feel I’ve gathered enough information and feedback to make an effective tutorial or guide so useful information can be shared. While I am no bastion of fine writing, you really don’t need to be, because information doesn’t care how it is conveyed, so long it is conveyed effectively. This means several things;

  • Users can read without misinterpretation
  • Users can easily re-interpret the information to suit their needs
  • Users can apply the information for a near-identical result

Notice the running theme? When writing anything for anyone else to use, even you five years from now you need to ensure the information written can lead to a duplicate result.

###Stuff about text formatting
When writing a tutorial like this one, how the text is formatted really does matter. It matters so much, I feel disappointed in myself when a bit of information isn’t formatted properly due to sloppy writing. Different websites may use different forum software; learn what commands you can use, and the limitations of that software.

For example; this website uses DIscourse, which allows for a blend of markdown and BBcode. Though, markdown may differ between websites and programs; Single asterisks *Like these* in Mibbit’s chat client bolds, while single asterisks on here will make text italic. Likewise, Discord uses double tildes for strikeout, while [s]this will strike out text here.[/s] While BBcode tags let you camel-format text, markdown disallows camel formatting*
(* Camel formatting is what I refer to stuff like this)

[code]Code is presented with graves. For this example I used [code] brackets
This can also do code, on Slack, Gitter and Github(?) triple-grave is used for formatted code.

  • This is an unordered list bullet point.
  • This is a bullet point within another bullet point.[/code]

1. This begins an ordered list. 2. So on... 3. So forth.

[code]1. Unordered can be nested in ordered, too…

  • Like so.[/code]

Previously, Discourse here allowed for the use of the [size] tag. Now, five levels of headings using pound signs / hashtags (#) can be used to make headings larger or smaller.

when writing a tutorial for a piece of software there are two levels of syntax you should be working with; The explicit syntax of a program, and the implicit syntax of your formatting. Things become more funny when trying to detail GUI elements without the assistance of screencaps, which will be discussed later in this guide.

Below explains the following of each;

  1. Explicit syntax
  • Machine code for compilation
  • Program commands for execution
  • Regex§ matching for situations which demand it
  1. Implicit syntax
  • Interpretation of tabs and fields
  • Emphasis, when required
  • Non-explicit operations, or operations non-interpretable as commands or code.

Try your best to limit implicit syntax, but what implicit syntax exists should be consistent throughout your writing. Implicit syntax can be heavily context-dependent, so when using multiple contexts for implicit syntax they should be distinct, with emphasis and all else being clearly separate from one another.

While I’ve never used an image in a guide, including them can be beneficial when there is no other means to explicitly define an operation and you wish to severely limit what implicit syntax exists for a clearer understanding. There are some caveats, though; Images can disappear at any time, limiting the longevity of a guide to the longevity of an image host. Image hosts may also shut down for maintenance, which would directly affect how well a guide is interpreted to masses of people while the image host is unavailable.

When using images, it may be better to have such images attached to your forum account, and loaded from the same location as the forum servers, which may also allow for your information, should a forum like this shut down remain usable if a web crawler manages to encounter your document.

When using images, you should provide implicit syntax for it anyway just in case, but then also have some key words used in writing apply to writing in images as well.

To make an image of a window, hold <shift> and press Print Screen. This key can differ in depiction on your keyboard, or may require the use of the <Fn> key being held as well. Should all of that fail, use a screenshot program, if applicable. For Ubuntu MATE (or anything using the MATE DE), mate-screenshot is an ideal command-line utility for this purpose, though there are others such as shutter if mate-screenshot does not suit your needs.

You may want to install and use gimp to further edit your image; Use a colour which stands out, and perform the following order of steps;

  1. Select box select or circle select
  2. Use either select tool to lasso around an object
  3. Bucket fill with an outstanding colour
  4. Go into Select > Shrink, use (at least) 3 pixels
  • You can also hold <Alt> and press S, then press H.
  1. Cut the new selection

Whatever you lasso will now be encased in a circular or box outline of colour. Use colour-matching text to detail the selection with whatever a user needs to see; it should relatively match what’s implied to perform identically to the text-only explanation.

Save the final result, upload it somewhere online and use the [img] tag to include it. It helps to write a text-only explanation first, then include images after since images can disappear, which means images should not be integral, but assistant to the text provided.

That’s all there is to it! You should now have all of the information you need to get cracking, and write long-winded solutions to problems very few may actually care about, but of the few who do care, may be thankful for your efforts.