Jump to content

  • Log In with Google      Sign In   
  • Create Account






Article Writing Tips and Advice

Posted by Gaiiden, 10 July 2013 · 1,281 views

I've been keeping notes over the past few months our new article system has been in use and have several tips for both new and current authors to make your content better for people to read and also better for me to work with when it comes to publishing them. All these tips are in addition to the guidelines help article.

On article length

There is no such thing as an article that is too short or too long. The main purpose is to sufficiently explain or talk about some topic related to game development. Articles that are too short are generally incomplete. Articles that are too long are generally full of rambling paragraphs and off-topic discussion. Here's an example of a good "short" article and here's and example of a good "long" article. If you feel your article is too short, then perhaps you should look deeper into the subject of the article and see what more you can talk about. If you feel your article is too long, then perhaps you should go back and edit it to try and identify/remove areas that aren't really important to the reader, or could be referenced out, or were written at 3am last night and make you scratch your head wondering what the hell you were blabbering on about. If you can't do any of those things, your article length, whatever it is, is just fine.

Writing article series

I hate article series. As a publisher, having unfinished article series means constantly having to nag the author for the latest installment after a month or two of no activity. As an author, feeling the pressure from readers (and me!) to finish up an article series you started half a year ago when you actually had time for it is stressful. As a reader, not getting the conclusion of whatever the series was eventually leading up to is disappointing. Please, please, please do not bother starting a series of articles unless you know you can finish them. This ties somewhat back into article length. Some people decide to break their articles up into a series simply so people are not overwhelmed by a huge amount of information in one sitting. If that's the case, then write the whole thing first and then break it down into parts - don't decide from the start it needs to be a series. I'm sorry to be all pessimistic about this but in the many years I've watched content on this site, the number of completed series is miniscule next to the number of uncompleted ones.

Let's look at a possible alternative - instead of saying "I'm going to teach you how to program in OpenGL", try "I'm going to talk about OpenGL programming useful for beginners". This makes your articles loosely connected, and doesn't promise anything. It's more like writing a column than a series. A good example is this article that kicks off a number of articles discussing topics on getting into games through education.

Again if you really feel like your topic deserves a deeply-connected series of articles, take the time to plan it all out, work up rough outlines of each individual article in the series, and even get some kind of writing schedule worked out so you can fit it into your normal work schedule. Despite what I said earlier about writing everything first, I will admit that producing the entire topic in pieces can get the information out faster over a span of time.

Do your own editing

If you want your article to get online as fast as possible, make it easier for me to get it there. My first step in reviewing an article is a quick scan of the content. If I find several spelling/grammar errors within or several things that don't conform to the content guidelines I'm going to assume that a closer look will just reveal even more. I'm not going to spend 15 minutes to an hour editing it when another submission could be quickly approved. If you are a non-native English speaker, try and find a friend who is that can proofread for you. Even if you are a native English speaker, find someone who doesn't mind reading over your articles even if they aren't a technical person. Do not submit your article for publishing the moment you have written the last paragraph. Go to bed, wake up and then go and reread the entire article at least once. I can't tell you how many "of"s should have been "off"s or "its" should have been "it's". Very small and very simple spelling/grammar mistakes can be caught by a simple read through - but they can also be missed. I've done editing passes on articles, published them and then found a new mistake. So let's double up on the editing so I can catch whatever you miss.

I seriously just edited an article that had "impost important" within a sentence. Considering the context I took it to mean "most important". It wasn't even an article with obvious bad spelling/grammar in it either. Maybe an improper autocorrect? Whatever, it's things like this you can catch on another read through. Or two.

Articles are not for help, project updates or announcements

We've had a few submissions that announced a new game, or asked for help doing something, or contained a press release/project update - none of these are appropriate for the articles section. If you have a game announcement or a press release, send it over to Your Announcements. If you have a question about game development, choose the appropriate forum to post it in. You might also want to consider starting a game development journal if you want to talk about your project in any way other than a postmortem.

When to write an article, when to post in your journal

If you have a development journal, know that any content posted therein is rather isolated from the rest of the website. The journal represents sort of your domain on the site and isn't deeply-integrated into the overall content system like the articles are. If you plan an entry that is very "outward-facing" (a postmortem, technical details on implementation of something in your game, etc) you might want to consider posting it as an article instead. Things like new features added to the game, troubles you had debugging some tricky section of your code, etc are entries I call "inward-facing" as they are mainly about you and your project rather than directly applicable to readers (although sometimes somewhat applicable - for example finding a bug in code you feel might be common for others). These types of entries should remain in the journal. You are free to post outward-facing content in both places, of course. Just know that the article version will be the one most-often pointed to from other areas of the website.
 
Use of article introductions

Unless you plan to use sub-headings (H2) in your article's introduction, there's really no need to have an "Introduction" heading (H1) at the top. Furthermore, there's no reason to replace "Introduction" with the full title of your article. I've gotten a few articles written outline-style with "I. Introduction" and "II. Some Other Section" and so on - if that's how you want to lay out your article that's fine. I won't mess with it by removing the top heading.

When to use H1

You actually don't need to automatically use H1 for all your article section headings. Both H1 and H2 do the job of creating a distinguished orange text heading to separate your sections, and unless you plan to use sub-sections in your article, you can use H2 for all your headings. You could even use Bold text as headings if you wanted and have no plans to use sub-sections under a H2 section. No, Italics as the only headings for an article isn't a good idea. In general we would prefer you use at least H2 for all headings in an article.

You can edit your articles

A lot of authors seem to forget they are the ones that created the article. In the past, authors submitted content to us in HTML, text or Word format and we published it for them. Any changes they sent to us and we implemented. Now, authors can go and edit their articles themselves to make changes and updates. So once your article is published don't forget to monitor it for comments from readers who may have suggestions on improvements or found mistakes in your text/code. You can keep an eye on articles you write and articles you like by clicking the Follow button at the top of each article. Then, go into your Settings and make sure your Notification options are enabled for resources.

Don't forget about Teletype Text

Some people use bold, italics or quotes to identify variable names, functions and code inside a paragraph. All of these are decent ways to identify code within an article (although italics is more commonly associated with mathematics variables) but none of them are good at making a reader instantly understand what they are looking at. If you see something written like this, any coder will instantly pick up that it's a code statement. It's very simple to go back and highlight a word or sentence in the editor and then use the BBCode drop-down list box to select the teletype text option so you aren't constantly writing out the BBCode yourself, which I agree can be annoying.

Use "No Spacing" in Word when drafting

I'll admit the lack of spell-check in the editor is annoying. Apologies. I'm sure most of you will be drafting up your article outside the editor, like in Microsoft Word or similar editor to take advantage of the spell-checker. If you're not, there's no harm in doing so. The only thing I would recommend is to make sure that every time you press the Enter key you are adding a line break, not a new paragraph. So if your text cursor is automatically jumping down two lines on Enter to create white space between paragraphs, that's bad. Because when you go to copy/paste the text into our editor all the paragraphs will run together. If you added line breaks, all the paragraphs will be pasted properly.

Notating articles for better feedback

I just want to end this entry by reminding you all that I started a discussion about article notation capabilities back in April and if you think this is a feature that would be useful to you as an author, reader or both please let us know! We're working on a lot of stuff right now and priority is simply assigned to what our community wants/needs the most.

Thanks for reading, and if you still have an article sitting around as a draft then I urge you to get around to polishing it off. I look forward also to those of you who have ideas kicking around in your head that still need to get drafted down. Keep the great submissions coming, it's very pleasing for us to be able to output roughly 4x as much content per month as we used to prior to 2010.




Re: Microsoft Word creating paragraph breaks instead of line breaks

 

Use [shift enter] instead of just [enter] to create proper line breaks.

This should be a help article as well..   ;)

Why is it that the journals aren't integrated with the rest of the site?  I love my journal, and it would be great if I could have additional visibility based on ratings or views or whatever.  Why not add the needed updates and make the journal system a first class citizen at GameDev.net?!

wish I had a good answer to that but it's mostly in the hands of IPS and how they tie their systems together. The more we do to bring them together ourselves the more we risk future updates breaking the site, or just causing more maintenance issues than we are able to handle

July 2014 »

S M T W T F S
  12345
6789101112
13141516171819
20212223 24 2526
2728293031  
PARTNERS