How not to write an article.

suggestions.md

Each exhibit has a codeblock containing git diffs. The - represents a section of text that should be removed, while + means a section of text that should be kept. Lines beginning with # represents a comment added by me.

Exhibit A - Textual Example

- In this article we take a look at how to downgrade from one edition of Windows 7 to another. For instance, if you have Windows 7 Professional, but would like to downgrade to Windows 7 Home Premium. You might ask, for what reason? Well, there are scenarios where this issue might come up. Maybe you want to reassign Windows 7 Professional to another computer, and install Windows 7 Home Premium on it instead. Maybe the edition is not being used effectively and could be more useful else where such as a laptop you carry to work since Windows 7 Professional includes a lot of business features. 
- The problem is the process of reassigning licenses, this would probably mean you will have to backup data, prepare to reinstall applications and drivers then restore data. All of this can cost some down time. 
+ Luckily I found a cool little third party utility that allows you do this with ease. Its called Windows 7 Downgrader. 
+ Windows 7 Downgrader will let downgrade popular editions such as Windows 7 Ultimate, Enterprise, Professional quickly and easily. Once it downgrades, all you need to do is insert the Windows 7 installation and do a repair upgrade to a desired edition. Lets take a look at how to do it. 
+ First you need to download Windows 7 Downgrader here
+ Save the file to your hard disk and extract it. 

As you can see, the first two paragraphs are completely useless to the reader when they search for an answer to a question. They waste time, making the user read other use cases associated with this fix, instead of just delivering the answer neatly. This annoys users, as they have to scroll through complete drivel first.

This style, if I'm not mistaken, is not as common on StackOverflow as it is on multiple "Linux" news websites.

Please keep your answers short and tidy, providing references and links. If the user does not get to the answer in under/5 seconds, something's wrong with your answer.

Exhibit B - Video Tutorial Example

This format can be seen on YouTube, where videos are prefixed with uninmportant bloat like this.

- [loud banging music for 10 seconds]
- Hey guys, welcome to my video!
- Hey guys, it's Cory, with another YouTube video for you to enjoy!

# This may be useful, and it is short and snappy.
+ Welcome to my guide on installing Arch Linux!

[installation guide]

The intro is useless to the user that just wants to know how to install Arch Linux, while the rest may be useful information.

Exhibit C

If your article is about a Linux/Chocolately/insert favourite package manager here package, then you should try to provide users with a little codeblock explaining how to install this package from the Command Line, e.g

# zypper install package

Try not to use shorthand methods like in when providing a sample like above, as it confuses users, and makes your script less transparent to people that are not familiar with the shorthand you're using. Have a look at this.

- npm i -D package
+ npm install --save-dev package

Now an unedicated JavaScript developer may wonder:

What does the -D flag do?

Which will either cause them to Google it, npm help it, or wing it, which are all slowing the user down. If the command does not include long flags, be sure to use # comments, or explain what they do in the paragraph.

Instead, make sure you use the long command line flags to ensure readability is at peak, and the user can infer what the command executes.

Save people time.