If you are a new author or unfamiliar with any of the types of content specified in the
How To Publish document, then below are some writing guidelines and tips to help get you more comfortable in creating your work. First we will discuss the best way to format your articles in general, and then we will discuss good practices for writing topcial articles, reviews, and how-to guides.
Quick Links
Formatting Guidelines
The formatting and layout of an article are key factors in its usability. Articles must not only be easy to read and follow in a linear manner, but they must also be easy to reference in a non-linear manner. To this end, we recommend the following format guidelines. While you do not have to adhere to them strictly, ignoring them altogether can possibly lead to votes of denial if your choice of formatting obstructs the article's readability. There are plenty of formatting tools to help you lay out your articles properly, below we go over some of the more common ones and how they should be properly used.
Main Heading
Main Heading
Sub Heading
Sub heading
Sub Sub heading
Sub Sub Sub Heading
Sub Sub Sub Heading
Shown above are the four ways to break down your article into sections, below each is the format tag that creates the section heading. If your article requires more than three sub headings we suggest you back up and review your approach. Ideally you should not need to break down a secion any futher then the second sub heading. All headings and sub headings reside on a line by themselves, with spacing above and below as shown above. The only time you should not use a heading is to label the first paragraph as "Introduction". Sections are important not only to progress the reader from one concept to the next but to make it easy for the reader to find an area of interest when returning for reference.
Within paragraphs, formatting should be used as well where neccessary.
Bold words and sentences stand out to the reader and should be used to highlight important terms and areas that would be useful for anyone skimming the text or returning for reference. Less subtle
Italics can be used to lend emphasis to words and sentences imporatant for those reading through the text. The use of ALL CAPS to lend importance to words or sentences is highly discouraged. Similarly, although Underline is available we recommend that its use is limited to avoid confusion with hyperlinked text. If you are using any code keywords or function names within a paragraph you can use the
Teletype font face to help distinguish these words and phrases.
.. you can use the Teletype font face to help distinguish these words and phrases
Sometimes you have large sections of text you would like to stand out from the rest of the article. In this case it is usually not a good idea to bold or italicize the entire section. Instead, you should use the Blockquote or Note formatting to create a visible break in the article. These sections are commonly used for quotes or side notes relevant to the main body of the article.
This is an example of a blockquote
This is an example of a blockquote
This is an important note!
This is an important note!
Tables are allowed to be included within articles, however they should not be used to actually lay out the article itself. Tables should instead be used as a way to present any data or information the reader needs.
We recommend that article images be Centered rather than left-aligned, and any captions be included directly below the images. Captions can be italicized but should not be bolded. Images that are referenced in the text should include an identifier in the caption, such as Fig. 1, Fig. 2, etc.
Horizontal lines are available as well, however their use is not reccommended. Headers should suffice in defining sections of your article for almost all purposes.
When referencing within the main body of the article using reference numbers, they should appear in brackets such as [1], [2], etc. These reference numbers should all point to a reference at the end of the article. You do have the option of using the "name" property of hyperlinks to anchor your reference numbers to the reference section at the end of the article if you wish. All references to online media must have a valid hyperlink. Alternatively, you may choose to reference online media directly within the article using hyperlinked text.
[aname=topical]
Writing Topical Articles
This type of content will focus around specific techniques, methodologies, languages, fields of game development, etc. Examples include designing levels for First-Person Shooters, working with new DirectX features, learning the ins and outs of a specific API, exploring the basics of game design, managing teams with Scrum, etc. A focused topic is essential for this type of content, should be conveyed immediately and delivered concisely. Writing "as you would speak" is excellent for drafting up these articles however it is suggested you take a few editing passes to consilidate your writing down to the core focus of the article.
If you don't really have a good idea yet what you'd like to write about, or have an idea what area you are interested in but don't have a good topic, check out our
articles idea forum to see if any of the suggestions help inspire you.
Who are you writing for?
The majority of visitors to GameDev.net are looking to gain experience and knowledge from professionals and to learn new techniques and methods to develop games on all platforms. We strongly support both the beginners and hobbyists looking to take part in the industry and the active professionals looking to improve their craft. When considering an article to submit, keep in mind these various audiences and make sure you choose the one(s) you wish to target before you begin to write. Some broad examples are:
Beginners
These people are just beginning to build an interest in game development and are looking for entry-level guidance on how to get started. They have usually played games, and they might have heard some disconnected fragments about how development works, but they're generally technically uninformed. Try and make sure that any technical terms you use are sufficiently explained, and don't try to cram too much information into too small a space.
Intermediates
These are people who have a decent working knowledge of most parts of game development. They've made some games, and might be headed towards pulling together something for a shareware release - or they might be junior programmers in the industry. These folks are usually most interested in information that helps to solidify and consolidate their understanding of things, maybe showing them new ways of doing common things or case studies of other projects. They're also interested in content that introduces them to topics they don't really know about, without treating them like a complete beginner.
Experts/Specialists
These are people who have a solid grounding in a particular area, are comfortable reading whitepapers and playing with cutting-edge stuff; they're usually employed in their field or pursue it very actively as a hobby. These are the people you can present your fantastic new shadowing method or impressive approach to team-based AI to. But take care: these are people who know their stuff and will notice if something isn't quite right, so make sure you've checked everything out, and include full references to support your ideas.
General Tips
Regardless of who you are writing for, here are several things we recommend you take into consideration:
- References should be included wherever possible, either as in-line links in the text or as a bibliography at the end. A "further reading" section is suggested as well when possible
- If you are planning to write a series of articles, know that the majority of article series do not get finished. We highly suggest writing all the articles in a series, and keeping the series under 5 parts, prior to publishing. Another method is to make the articles into a "loose" series that follow a common theme or topic and do not depend tightly on each other. Either way, make sure your series includes links to all parts within the article
- Ideally, by the time you submit your article you should have researched all the information you needed, but don't be afraid to admit that you don't know something. It's better to do that than to misinform people, especially when someone who does know it calls you out
- Compilable code is not necessarily the best way to demonstrate a concept, even when commented. Consider whether pseudocode would be clearer. That said, if you're going to include a downloadable code package to accompany the article, make sure it compiles
- Real-world examples are great. Use as much of your own experience as possible but be mindful of revealing any confidential information in the process
Structuring Your Article
Below are the main sections all articles should contain, when necessary, to create work that will be readable and usable by the community.
Introduction
You should begin with a paragraph or few that defines the topic of the article and includes any background information relevant to techniques or theory that will be discussed within the article. Make sure the reader also gets a clear understanding of the level of proficiency required to be able to understand and use the article. Unless you choose to precede this section with another, there is no need to actually title this section as "Introduction", as it is the top of the article and needs no separation from the rest of the body.
Main Article Body
Here is where you begin with named sections and delve fully into the main topic of your article. All authors have different preferences in how to structure the main body of their article, but we do ask that you try to adhere to the previously-covered guidelines above as much as possible to ensure good formatting that will pass through the initial review stage.
Conclusion
Summarizing your article, like the introduction, can take a single paragraph or several depending on the depth of the topic under discussion. The conclusion serves primarily to identify key points from within the article that the user should remember for later reference. You've just spent 5 pages explaining a technique to someone but where in those thousands of words are the "gotchas" or precise data points people need most to make it all work?
Further Reading
If you have only scratched the surface of a broad topic, or only provided an introduction to an advanced technique, you may use this area to direct readers onwards to collect further knowledge on the subject you just covered. This would include books, magazines, and other online articles.
References
If you reference something anywhere in your article using a reference number, this section will contain the full reference information related to those numbers. It is important to reference as much as possible in your article, regardless of how much you feel readers should be able to trust anything you tell them. Not only do references back up your words, but they can also save you the trouble of having to explain things to the reader yourself.
About the Author
This is a section many like to place at the end of their articles to give background on their expertise to let readers recognize their ability to cover the topic of the article. Please, do not write a full bio. A paragraph at most will give people an idea of your qualifications related to the subject matter. We actually recommend that you leave out this section entirely and instead keep the About Me section of your user profile updated with all of your qualifications. This will save you time from having to re-write this section multiple times or go back to edit it if anything changes.
Article Changelog
You may choose to keep readers informed of changes made to the article over time, which can include code corrections, new/removed material, and major corrections in text.
[aname=review]
Writing Reviews
Before writing a review of a software or hardware product you should ask youreself if you are qualified to do so. First and foremost for an unbiased review you should have no relationship, either directly or indirectly, professional or otherwise, with the product in question. Second, you should be a user of that product yourself, not giving a second-hand report based on what you have seen or heard about the product. Third, you should be able to give a balanced account of the product's performance - all bad products have some good points and all good products have some bad ones. A one-sided love/hate affair will not fully benefit readers of the review.
Remember that the purpose of the review is not to inform people on what a product does in general - the marketing team of the product has that job. As a user of the product your job is to inform others on where the product falls short and where it shines under actual usage according to your time spent with the product. If you see a review already exists for the product, make sure the review covers a similar style of use to yours before you decide not to write an additional one.
Instead of writing a review to directly counter a previous one or add to an exisiting problem highlighted, please comment on the review in question.
Structuring Your Review
Below are the main sections all reviews should contain to create work that will be readable and usable by the community.
Introduction
Use the opening of the review to detail your use of the product. If it is software, what system are you running it on? If it is hardware, what environment is it being used in? If it is a book, did you just read it casually or are you using it actively to refine your latest engine design? This is important in giving the reader the proper context for the rest of the review. As with topical articles, there is no reason to actually title this section as "Introduction" unless it is preceded by another for some reason.
Main Review Body
Here is where you detail any issues you have experienced while using the product and any benefits you have gotten from using the product. How you decide to do this is up to you. You can create two main Good and Bad sections and sub-section them into individual issues, or you can simply look at certain aspects of the product one at a time and discuss the good/bad side of each. The important thing is that you do not simply say "product X has a bad interface" without going into details - images and use cases - that explain to the reader why the interface is bad. If the reader happens to be related to the product, maybe the next version will solve some of your problems.
Conclusion
Your review summary should state how you felt the product has performed overall according to the usage details you provided in the opening paragraph(s) of the review. If there are any general statements to be made on the improvement of the product, they can be made here also. At the end of the conclusion there should be a list of Good/Bad product qualities, each list item being 1-2 sentences long. While you can use this to include minor good/bad qualities that didn't warrant extended commentary in the main review body, the primary purpose of this Good/Bad list is to reference everything you covered in the main review body. Readers skimming your review can use this list to determine if there are any issues with the product they would like to go back and read more about.
About the Author
We ask that you follow the same advice given in the structure section for [alink=topical">topical articles.
[aname=howto]
Writing How-To Guides
A how-to guide is our term for an article that is comprised of steps leading towards a specific goal. "How To Create a Window with DirectX 11" or "How To Texture a Model in Blender" are both basic examples of how-to topics, which can focus on a tool, API, language, engine, etc. Each section should be a well-defined and successive step towards achieving the goal specified in the title.
These guides are meant to be read by users of the software/hardware the guide is focused on and are not meant to be instructional or informational outside of their defined topic. For example, a guide on advanced modeling techniques in Blender should not have to touch on any basic use of the interface. Use the opening section of the guide to inform the user what skill level is required and provide links to any material the user can read prior to using the guide if needed.
Before you decide to write your how-to guide do some research and make sure similar resources do not already exist, so that you may instead use your time to focus on another topic. Most of a product's basic and intermediate functions are already covered well within the product's own help documentation, so try to focus on more advanced areas that don't see as much attention.
Structuring Your Guide
The structure of a how-to guide is similar to that given for [alink=topical">topical articles, the only difference being that the main article body will be a lot more progressive as you advance the reader from one step to the next. You may choose to simply make each main section a step, or define a section as a Major Step and have Minor-Step sub-sections to break down complex actions. All other article sections should be included as well where neccessary.
Questions? Comments? Feedback?
If you are feel you are need of further guidance or have any questions on the above, please
email our editor Drew Sikora.
