Tips for writing a good guide
There's tutorials to be written! Get into it!
Writing a good tutorial/guide takes more than a list of instructions on a page. There are many factors which must be considered before and during the process of writing to ensure that the end product is suitable. I've decided to write a series of tips to assist contributors in a group project on the Atomic forum. This project involves writing a collaborative overclocking guide. You could say that this is a guide for writing guides!
Spelling and grammar
Many would find this pretty obvious, yet spelling and grammar is often a second thought when it comes to online guides. Spelling and grammar isn't just a formality, it's about keeping a piece of writing readable and accessible. Not all readers will have the ability to consume dodgy writing, for instance, those who have vision issues and require accessibility tools. These tools will struggle unless you put the effort in. In addition to this, those who may not be able to read your chosen language will have trouble translating the document using translation services.
A well written guide has other advantages too. The first is professionalism. If you were offered two texts, one written in SMS-esque English, and another in bog standard English, then it's fairly safe to say that the latter will be most desirable - assuming both are comparable guides. Another benefit is its increased chance of getting search engine hits when people search related keywords. It may also entice popular sites to promote your work (think Slashdot, Digg, etc.) If you have the knowledge and skills required to write well, flaunt it! And don't be afraid to ask people to read your work before you publish it.
Plan your writing
Jumping into a guide head first is perfectly acceptable, but it can get tricky. Writing up a plan or quick outline of what you're going to cover can make the process significantly easier. I personally write a list of subheadings I aim to elaborate on. As I fill these subheadings with information, I append the document with small dot points about ideas, changes or additions I should consider when I have the time to do so. When all the subheadings are complete, I read the dot points and alter the guide accordingly. This process is somewhat recursive, until there's no dot points left to consider.
Work out what writing methods best suit you. My method may or may not work for most people, so don't be afraid to experiment.
Awareness of scope
Scope is the extent of, or 'reach' of the guide. Many topics, especially in computing, are very broad. It's important to be aware of the scope you wish to cover in your guide. If the scope is too small, important information may be omitted, rendering the guide incomplete or ultimately useless. An example would be writing a beginners guide to overclocking a particular platform, and not explain how to enter the BIOS, or what the settings you're changing actually do. Don't alienate the audience you're targeting, in this case, people who are new to overclocking. This is a mistake many intelligent writers often fail to recognise; just think of the most confusing textbook you've ever read, and all the assumptions it makes of the reader.
If the scope is too large, or you're going off on unnecessary tangents, the guide may become excessively long and difficult to write. Remember that someone will be reading your guide to learn about a specific topic - having large sections of text with little relevance to this topic may cause readers to turn elsewhere in sheer boredom.
Target audience and assumptions
It's critical that you work out who your target audience is. There's a vast difference in writing style between writing for novices, and writing for professionals. A novice will often struggle when it comes to jargon or low level concepts. On the other hand, a professional will rarely want to read about seemingly obvious topics.
Once you've worked out who you're writing for, stick to it. Don't start off explaining every detail, then as the guide progresses, assume they've magically advanced enough to tackle new topics without going into specifics. Consistency is key.
Consecutive topics and formatting
Your guide should be constructed in a logical manner. Readers prefer not to jump back and forth within a text to work out what's going on. The guide should be written in a consecutive manner, such that information used within more advanced topics are covered first. This helps to build up a foundation of knowledge so that people who are learning can ease into the difficult concepts that the guide covers. It also avoids the confusion induced by flicking between pages in an attempt to make sense of what's being taught.
Sometimes simple ideas have complex explanations. In that case, it's ok to teach the idea in an abstracted manner, and cover the complex aspects later in the text. Starting too complex in order to provide a complete picture can cause more issues than keeping it basic.
Formatting the guide with clear headings, chapters, and parts will help the reader navigate and encapsulate what's being taught. Breaking a guide into many sub-headings is typically a great way to a) work out what you want to cover, and b) allow the reader to get a quick idea of what that section covers.
Clear definitions of jargon
Once thing that catches out many readers is jargon. A term that's second nature to you, like the acronym 'LCD', may sound like gibberish to someone else. It's important to explain key terms within a guide. Whether you do this by adding another section, a boxout, or a glossary, depends on the style of writing and method of publishing. Whatever you choose to do, be consistent.
Use multiple trustworthy sources where possible
As humans, we tend to gather information and store it in our heads, particularly with topics we enjoy. Unfortunately this information isn't always correct. After writing a section of a guide, it is important to do a bit of research to ensure what you've described is indeed factual. People are easily fooled by myths, fictional anecdotes and wives tales, so double check all information you have acquired.
Multiple sources help to distinguish between fact and fiction. However, don't rely on publications which have a negative reputation. An example is Wikipedia. It's fine for getting an idea about a topic, but don't rely on it. Instead, check out the sources listed at the bottom of the page, and read the raw information first hand. On that note, try to locate original information sources where possible. Secondary sources may alter aspects and introduce incorrect or biased material.
Keep it simple
Don't write in a verbose or overly sophisticated manner. Unless your guide covers the history of the English language as an art form, write in basic English. No one wants to have a dictionary at their side to make sense of what's being said. If you're able to share your knowledge in written form, then there's no need to impress your readers by writing like a sixteenth century nobleman poet.
Don't bullshit
If you don't understand something, don't write about it. Do some research if you have to - take it as an opportunity to learn something. No one wants to read half baked information which has more assumptions and errors than raisins in a fruitcake. Sometimes you're better off leaving a section out (assuming it's not required), than to publish so-so material.
---
I hope this guide assists those who've taken the time to read it. Good luck!
