Tips on writing documentations

Tips on writing good documentations/guides​

After reading quite a few documentations that show definite potential but fail due to lack of effort, grammar, and more I've decided to give out a few pointers to those who are interested in becoming a User Educator or for those who are just wanting to help out other members. By following one or more of the tips provided below your guide stands potential to be more informative, clearer, easier to read, and overly better.

Table of Contents:
To find a specific section press "CTRL-F" on your keyboard and copy/paste the section title into the space provided.

• Information on writing a guide
  - Choosing a subject:
  - Laying out your guide/keeping your guide organized
  - Writing your guide
  
• Final Steps
  -
  -- Proof Reading
  -- Check spellings/grammar
  -- Final Read Through

Information on writing a guide:

A lot of users come in here thinking that if they write enough guides they will become respected and will automatically become some of the 'guide masters', well, they're wrong. In this section; quality overcomes quantity every time. If you spend an hour on a guide you have a 90% chance of your guide being better than the guy/gal who spent ten minutes on his/hers.

When you're writing a guide remember that you can only interest people about things that you're interested in as well. It is very difficult to write about something you have no interest in and to keep it interesting for the readers.

Below I will provide you with some tips on choosing subjects, how to organize, and more.


Choosing a subject:

When choosing a subject you must bare in mind that you can only keep readers interested in something you are. It is very difficult for a writer to interest a reader in something that the writer isn't interested in himself/herself.

When choosing your subject:

• Be certain that you have enough information on the subject to provide the reader with what he/she needs.
• Be sure you're interested in the subject
• Ask yourself if your subject will actually help/interest users
• Ask yourself if the subject you will be writing about has been done before, and if it has; what will your guide have that the other doesn't?

Laying out your guide/keeping your guide organized:

Another very important aspect of writing a guide - the layout. Keeping your guide organized, spaced, and well placed is very important. Without proper organization your guide risks being overwhelming to users. What I mean by this, is that you want to avoid having large sections of pure text. You can break up this text by using paragraphs, pictures, or merely using different colors.

A basic layout you can use is something like this:

[b][center]Titlehere[/center][/b]

Information on your guide. (give a brief summary of whats in the guide)

[b]Step One:[/b]

Text here for step one

[b]Step Two:[/b]

text here for step two

The use of paragraphs is quite necessary in guides. It keeps everything fresh, and easy to navigate.

Things to remember when organizing your guide:

• Bold or underline important subjects.
• Keep everything well spaced out.
• Be sure to provide images when possible.

Writing your guide:

Now you have your layout and your title/subject made you can finally get around to writing the guide itself!

While your writing be sure to be descriptive! It makes all the difference when trying to keep your guide interesting and keeping everything simple for those who are trying to learn from your guide. Remember! Not everyone knows what you do - when writing your guide work from the very first step. Don't start off assuming people know what you're talking about.

Show some personality in your work. Don't be a robotic figure who is strict, and has no personality. Add some emoticons, pictures, anything that can lighten the mood of your guide! Be sure to use exclamation marks (!) to add spark to your work(s) and other expressions such as jokes, 'lols' or anything you wish!

Last, but not least be sure to use proper grammar! Refrain from using slang terms such as "u" and not capitalizing "I", makes a huge different when saying things like:

hey buddy how r u?

Hey buddy! How are you?

Below I've made an example of a small article. The first, being before I followed any of these steps, and the second being after I followed them.

Making lots of money on RS

to start off with we have to get lots of hides or ess we will do hides for now. after we finish getting about 1k hides we can go to the grand exchange and sell them. now we have 50-90k we can now start our journey to merchanting. you can choose to merchant whatever you want really. you just need to know what the price will do next. you can sell tan cavs right now for example, that are selling for 26k a piece when they usually sell for roughly 100k or so. thats nearly 80k profit! here are some recommended items to merchant: pots, essence, platebodies, phats, santas, and yeah.

Now, if I was to edit this article to follow the suggestions I've provided above it looks better PLUS it's easier to navigate! With some minor edits, but using the same information I've re-written the below guide to follow some of the above suggestions to be more informative and easier to navigate.

Making money on Runescape​

Are you having trouble making Runescape money? I've written a small guide on how you can make some simple cash to start your journey to merchanting.

To start off:

To start off with we will need to find a primary source of money. I recommend rune essence or cow hides as they're both fairly simple to get and usually have a high demand causing them to be very easy to sell using the grand exchange. If you're killing cows to get hides you should get about 100k's worth. (about 1,500 hides) or 100k's worth of essence.

Step Two:

Now you've 100k! Sell your hides/ess if you haven't already and open up the grand exchange. Here is where your true journey begins. For today we will be merchanting Tan Cavailers...

Final Steps

So you've finished your guide and you're ready to post it? Lets hold back for another five minutes shall we? To perfect your guide it is highly recommended that you follow the below steps:


After writing a guide/documentation remember to:

1. Proof read
2. Check spellings/grammar
3. Final read through

Proof Reading:

Proof reading: one of the most important aspects of writing a documentation/guide. By proof reading your work can notice errors that you couldn't have noticed when you were in the process of writing. When proof reading; mainly focus on the 'sense' of your work. Ask yourself these questions as they're the questions your readers will subconsciously ask:

• "Does it make sense?"
• "Will people with no knowledge of the subject be able to understand?"
• "Have I made any layout errors?".

These are all important questions that the readers will subconsciously ask.

Check spelling/grammar

With spellings and grammar being in such demand in this time it is very important for you to use proper grammar. By having good spelling and grammar you can improve the readers' understanding of your topic. Without the usage of proper grammar you will seem childish or lazy, which will affect the reader's opinion of your guide. It is recommended to run your guide through a spell check whether it be on the internet or on a home program - either works.

Final read through

Your last chance to find any errors you have made within your guide. This will be one of your last chances to find things that will displease your reader.



I wish you good luck with your guides! With any luck you'll be able to provide users with information that they've never been able to find before!

--

I will be continuously updating this, as I still have quite a bit more to write although it's of sufficient quality to be posted now. ^_^

Thank you for reading my guide and I hope you all can provide some great insights, suggestions, and criticism for me to improve.

Also, I am aware of the article written on writing guides, but I wasn't aware of it until I was halfway finished writing this so please bare with me. This is all my own work, none was copied. Thanks again!

 

[Python]

I've seen to many of these, sorry. I don't think it was needed to make it.

 

Like I said at the bottom I'm aware that there was one already made and I'm not looking to replace it. When I briefly looked at the submissions forum I didn't see any, until halfway through at least. I'm looking for constructive criticism on my writing, not the subject choice. Thanks again.

 

[MatthewGor123]

As Python says...there are too many of these. But, if you're looking for writings tips, at least try to follow your own guide! Proper spelling and grammar? I've read through two sections, and your comma usage is quite off. If there's an extra punctuation mark/something that needs to be deleted, I put it in colored brackets. (ie; this[,] is sweet)

Proof Reading:

Proof reading[,]: one of the most important aspects of writing a documentation/guide. By proof reading your work(s), you will notice errors that you wouldn't have noticed when you were in the process of writing. When proof reading, mainly focus on the 'sense' of your work. Ask yourself these questions: [FORMATTING COULD BE BETTER HERE, IE;]

• "Does it make sense?"
• "Will people with no knowledge of the subject be able to understand it?"
• "Have I made any layout errors?"

These are all important questions that the readers will subconsciously ask.

Check spelling/grammar (spelling would NOT be plural in this case, as you are basically saying you must check your spelling and grammar, not look for the many misspellings in the sentences)

With spelling and grammar being in such demand in this day and time it is very important for you to remember to use the best grammar [that] you can. [THAT WAS A VERY AWKWARD SENTENCE] By having good spelling[,] and grammar you can improve the reader's (I am assuming the meaning you want is you can improve the understanding of the reader, not of the readers as generally, only one person at a time will read your documentation/guide) understanding of your topic. Without the usage of proper grammar, you will seem childish[,] or lazy, which will affect the reader's opinion of your guide. It is recommended to run your guide through a spell check whether it be on the internet[,] or on a home program[,] - either works.

BTW, you might want to recommend checking for spelling/grammar manually as well, because there are tons of homonyms that can alter the meaning of the sentence significantly (like their and there, bee and be, etc.). You can link to a list of common homonyms, too.

 

You're actually quite right. In the end I was a bit in a rush, as I had to go off somewhere. I wasn't really worrying about the punctuations because usually I'm pretty good with them. Although every once in a while I go into some sort of a "mode" where I'm just talking (but typing) and using commas to show how I would say it in real life.

Thanks for pointing those out, and I'll edit the article. ^_^