How to create “HOW-TO”
And what to look out for, when you create them
Version and revision: V1.0 / R0.
For: Nethserver documentation authors
Skill: General audience.
Published: 2015-10-17
Review: 2015-10-17
Author: Bogdan Chirica
Contact: Nethserver community forum: CTek
Description
This short guide will present some of the general points that any author should take into account when he/she is creating an “How-to” document or video presentation.
0. Take your time.
Do not make a hasty “How-to”. Do not rush things, you might miss something. Keep organized and take your time.
1. Know your stuff.
You have to first know and understand what you are about to present. Some authors create the “mechanical How-to’s”. Meaning that they are putting together a list of steps that worked for them without knowing too much information about the operations presented.
This is ok as long as nothing changes in the hardware/software they are using and as long as the setup can be replicated. Otherwise, any change could make the “How-to” useless.
2. Prepare before making the “How-to”.
You have to be sure that what you want to present is working. This means that you have to do at least the steps yourself before publishing the document.
3. Take notes during the initial experiment.
Even if it is a hardware or software “How-to”, you must verify and write down, every step of your experiment.
This will help you to create the document without missing any steps.
4. Target audience.
Independent of your skills, the document may be read by veteran users or novice users.
You have to take this into account when you prepare the document.
5. Keep it in simple words.
Do not try to present your writing abilities in the document (write a novel if you desire but not in the “How-to”).
Use plain simple words. Do not use very difficult technical words, otherwise this may end up confusing the reader.
When you have to use such words, try to put a short definition / explanation in a note or parentheses.
6. Do not assume anything!
Build your document with the novice level in your mind. Present the steps and then try to create a short explanation of what happened in that step.
When available, put some links to more information regarding that topic.
For example: If you present a step regarding a network setup, try to present the IP and the Subnet and Gateway. Then you can add some notes explaining what the IP means and what Subnet means with explaining the /20 /24 /28 meaning. Also put a link or description for Gateway meaning.
You might know all this by heart but a total novice will not.
7. Present alternatives.
Keep in mind that all the setups are unique. Even with hardware devices, it will happen. The same model of device can be manufactured in two or more formats, revisions, firmware can differ etc. Take this into account and try to point out alternatives.
If you describe a setup, present the alternatives that a novice can use. Don’t go rambling from the start that only X should be used without presenting an alternative to X.
Not everybody uses X !
For example: "Start your setup in VmWare and build a Golden Template machine …. "
(As an alternative to VmWare, you can use Proxmox, OpenCloud, Interactive CloudOS, XEN etc with their setup constrains and settings).
8. Be very clear when exposing your ideas.
Do not make a mix of multimedia without showing the relevant stuff.
If you present images in your “How-to”, make sure you add captions or you write a text above and under that picture. You HAVE to explain what is in that picture and what the user have to do in order to obtain that same image.
9. If you make a Video tutorial.
Take care to have a clear crisp image and sound.
It is easy for somebody to opt for a video tutorial but this will not mean that the finish product will be good.
9.1. Make sure that you know how to capture the images correctly. Read some “how-to’s” on this issue. Use a screen capture program and not a phone or camcorder.
9.2. Edit your video and add voice explanation. Make a script that you are following while recording (Step 1: Present topic; Step 2…).
And, after what you have watched your work, read it clearly into the mic as audio.
9.3. Edit your film and add stop moments when you explain better what is going on into the image.
9.4. Add captions to the still pictures.
9.5. Keep in mind that the user that is watching may want to do the steps presented while watching the video! Make any recommendation BEFORE the step is executed, NOT AFTER!
For example: If you present the “rm” command, explain that you will present a powerful command that can damage the system before you say/show the command! NOT AFTER! (or you may receive a lot of “best wishes”).
10. Stage all the components that you will use in the tutorial before.
Prepare your tools, demos, test machines / programs etc, before you make the tutorial.
Going back and forward between setting up something, in the actual process of setting up something else, is not easy. Especially for new users/readers!
For example: If you explain the setting up of network settings, do not present in the middle of the process how to create the patch cables.
Do it BEFORE or create another “how-to” and put the link as reference.
11. If you are making a written “how-to” try to keep a simple/standard format.
Create a template document that you will use. It should have the same structure as the other “how-to’s” in that category.
Example (for header of document):
Version and revision: V1.0 / R0.
For: Nethserver documentation authors
Skill: General audience (Novice / Beginner / Intermediate / Advanced / Developer).
Published: 2015-10-17
Review: 2015-10-17
Author: Bogdan Chirica
Contact: Nethserver community forum: Ctek
For example: Put the pictures on the left and text on the right. If you choose this way, keep it the same.
Another example: Put text that describes the step before the picture and text that explains the actual steps under the picture.
Do not mix formating along the document if possible!
12. Requirements.
Create a “Table of contents”, “Glossary”, “reference and more links” and “list of materials/requirements” needed in the “How-to”.
Put “The header of the document”, “Table of contents”, “list of materials/requirements” tables at the beginning of the document and “Glossary” and “reference and more links” at the end.
12.1 Create the header of your document.
Create a header of the “how-to” that you will populate with the information needed by the reader/user, to identify the purpose of “How-to”.
Also, it will be the template of you future “how-to’s”.
Title: “How-to” create a proper HOW-TO’S – give it a meaningful and clear title
Subtitle: Short explanation of the basic points to take into account when creating a “how-to”
Version and revision: V1.3 / R 0.2. - Revision means that after you have published the document you correct/improve/add some steps.
To what it applies: For Nethserver 6.5, 6.6, 6.x. - Do not put simply Applies to Nethserver.
Required skill level of the reader/user: Accessible to: Novice / Beginner / Intermediate / Advanced / Developer.
Date of presentation: Released on 2015-10-15
Date of the latest revision: Revision: 2015-10-17
Author: Bogdan Chirica
Contact: address@somedomain.com
13. Set your conventions in the beginning of the document.
If you are going to present some instructions that require particular attention, make sure you warn the reader/user/viewer about it.
Specify at the beginning of the document that any paragraph starting/containing any of the following, requires more attention:
[WARNING] – Meaning that the actions may cause damage to the user or to the Hardware/Software involved.
[ATTENTION] - Requiring from the user to pay extra attention to the instructions in that step.
[EXACTLY AS SHOWN] – Requiring from the user to do exactly as shown and no other way!
[OPTIONAL] – This step is optional and it can be skipped or not, depending on user preference.
[ALTERNATIVE “X”] – This is an alternative step to another X step. In case the X does not apply.
[NOTE] – This is a note that explains better or adds explanatory value to a step.
You may find that you can add your own conventions like [Link] [Reference] etc. But keep in mind that the user should read this conventions PRIOR starting the steps presented in the “how-to”.
14. Add bibliography or specify the authors of the other work you have used or have mentioned, if it is the case.
Nobody likes their work to be stolen! Even if they have consent that it is public information, it doesn’t mean that they don’t deserve the credit. Do not assume someone else’s work!
[Note] Take a positive approach. Do not treat/address the reader too harsh. They are reading your document after all!
Do not have a tone of superiority and ALWAYS remember that in the beginning, you were a novice (noob) too!
