Help talk:Style Guide

International Game Developers Association

The commentary below refers to a previous version of the Guide and is out of date. Please start new comments here:

Table of contents 1 Referencing/citing 2 Sections 3 Article titles 4 Encyclopedic articles? 5 Auto-generated titles? 6 "Embolden" 7 Recommend against underline 8 Acronyms 9 Abbreviations 10 Compound words 11 Hyphenation

[edit] Referencing/citing

How should we cite references within this framework? We have several references within the Casual_Games_SIG/Whitepaper/Market_Overview but I'm not sure how I should put those in Dubane 12:06, 29 Dec 2005 (EST)

[edit] Sections

When you refer to "Sections" do you mean sections of articles? I mean, does a group of articles make up a section? or does a group of sections make up an article? (a single page) I'm really not trying to be difficult, your usage here is ambiguous. Clarification would fit after this sentence: "There are two orders of titles: titles of articles, and titles of sections." Perhaps, "A single article can have several section headings on its page." It might be good to then refer to them as "section headings" instead of "section titles" so that the word "title" doesn't have two different meanings. WendyDespain 20:16, 23 Sep 2005 (EDT)

If a wiki is made up of articles, then articles are made up of sections. Good point about "section titles" versus "section headings" though. Adraeus 22:20, 23 Sep 2005 (EDT)

I didn't know you were thinking of the wiki as made up of articles. In my vernacular, a wiki is made up of pages, as any other generic website is. I thought you were using "article" to describe a specific kind of page with a specific purpose (encyclopedic information). The term "article" - doesn't accurately describe 90% of the pages in, for instance, the writers SIG. Those are pages where we work together to organize projects, edit working manuscripts, etc. They're not going to be finished informational articles. Most of the contributors here have no background of any kind with wikis. We have to be very careful about terms we use. I'd like to use the term "page" rather than "article" throughout this style guide. WendyDespain 00:40, 24 Sep 2005 (EDT)

The term article is defined as "nonfictional prose that forms an independent part of a publication". [1] Is that not an accurate description of the nonfictional prose contained within the "pages" of the Writing SIG? Part of my job as wiki manager is to encourage contributors to use this wiki correctly for the purpose that Jason has envisioned. This includes introducing users to the wiki lexicon. In the context of wiki technology, an article is not a "finished" work due to the nature of open collaboration, but rather a progressive work that is acceptable to its editors. The construction work that produces an article takes place behind the scenes in the article's Talk page, where not all prose is nonfictional and not all writing is prosaic. Adraeus 04:18, 24 Sep 2005 (EDT)

Mediawiki is not the only wiki software in the world. "Article" is not a standardized term throughout all of wikidom, and personally, I don't think it's the best word to use here. It evokes a formal, published work - not a living collaborative editing space encouraging participation. If you don't like "page" what about "workspace" or "document"? WendyDespain 17:56, 27 Sep 2005 (EDT)

I like "project" and "workspace", and given the new nature of this wiki, I prefer "document" over "page" and "article". If you'll support me, we can work with these terms instead and work on their definitions.

• project: IGDA New York City and Game Writers SIG are projects. Projects are described and provide a descriptive index of project-related documents. Additions, editions, and deletions are not manually signed or timestamped in a project.
• workspace: Talk:IGDA New York City or Talk:Game Writers SIG. A workspace is where civil, organized, and professional collaboration should occur. A workspace is also where project-related discussions should occur. A workspace requires contributors to sign and timestamp their edits.
• document: Game Writers SIG Quarterly. A document is neither a project nor a workspace, but the content is either subject to radical change or extremely polished.

Adraeus 06:28, 11 Oct 2005 (EDT)

[edit] Article titles

I don't understand this....

   Incorrect: Information on Breaking into the Industry 
   Correct: Game industry

In the context of this wiki, an article titled "Game Industry" is far too broad and vague. This entire wiki is about the game industry. WendyDespain 20:16, 23 Sep 2005 (EDT)

Jason and I discussed the purpose of the wiki further, and we decided that this wiki becoming a knowledge repository for the games industry was outside the original scope of the project. In addition, the example is meant to illustrate that article titles should not be specific, and exactly as you pointed out, "broad and vague". This is done so that the article may delve into the specifics of the topic which the article title represents, and thus, so that articles for every little section are not created. This is needlessly happening on some of the Chapter and SIG articles. Adraeus 22:20, 23 Sep 2005 (EDT)

I'm sorry, I still I don't understand why specificity is bad. Broad and vague = confusing and lacking direction. The homepage on this site may as well have the title "Game Industry" as everything within the wiki is about the game industry. What here wouldn't go on a page with that title? If we begin to have three thousand articles on the wiki, then we could look into combining existing pages that have similarities. But a page in the writers' wiki about documentation is going to need to have a different focus than a page in the QA SIG about documentation. Eventually we may want to cross reference the two pages, but they shouldn't start out on the same page. Writers will edit it to fit their needs, QA will edit it to fit their needs - it sets up needless conflict. WendyDespain 00:40, 24 Sep 2005 (EDT)

Think of a hierarchical folder/file database structure. An article with the title Quality Assurance SIG concerns everything about the Quality Assurance SIG. The article is not titled Introduction to the Quality Assurance SIG or Overview of the Quality Assurance SIG, because those names are unnecessary. Everything about the Game Writers SIG should be in its article first, and then split into separate topics if the article becomes too complex and long. Adraeus 04:18, 24 Sep 2005 (EDT)

The "Quality Assurance SIG" example is far more clear than the "Game Industry" example. Can we use this one on the Style Guide instead? Also, I disagree that everything belonging to the Game Writers SIG should start out on the main page. For instance, it doesn't make sense to include there a collaborative book outline, which is one of the sig's inniatives. I do agree that they belong in the same section and that the outline should be referenced from the main SIG page. WendyDespain 17:56, 27 Sep 2005 (EDT)

Okay. I agree with you here. Adraeus 06:29, 11 Oct 2005 (EDT)

[edit] Encyclopedic articles?

Under "Organization" is this sentence: "An encyclopedic article should be written in paragraph format, divided into sections where appropriate, and organized by component in the following order:"

What is an "encyclopedic article" and how is it different from other articles? Is there a specific section of the wiki set aside for encyclopedic articles? Oh, are the sections mentioned here the same ones described above? Maybe this explanation should be moved up. WendyDespain 20:16, 23 Sep 2005 (EDT)

Since the wiki is to no longer function as an encyclopedia for the games industry, for explanatory purposes, consider that an "encyclopedic article" is simply a well-organized article of nonfictional content that communicates information clearly and effectively to readers. Adraeus 22:20, 23 Sep 2005 (EDT)

How bout we pick a better word for the style guide instead of re-defining the term "encyclopedic article"? If you mean that all pages should be organized this way, let's just say "Pages should be written in paragraph format...etc." But if that's what you mean, I have to disagree. Once again, we need to compile lists, make outlines etc. that shouldn't be written in paragraph format. I'd hate to encourage users to disregard the style guide. WendyDespain 00:40, 24 Sep 2005 (EDT)

There are lists and outlines in an encyclopedia, but that is irrelevant as is this narrow focus on which terms are used. The style guide, policy manual, and usage guide are under construction. This wiki is under construction. By the way, there is a section regarding lists in the style guide, but only a portion of the style guide is online. If you look at the style guide as a guide, you will more successfully coexist with it. Adraeus 04:30, 24 Sep 2005 (EDT)

I recognize that it is under construction (though I do like the new template you put at the top of the page - much more friendly) and I'm trying to participate in its construction. Is this unwanted? WendyDespain 17:56, 27 Sep 2005 (EDT)

Yes. I'd rather we concentrate on a "Best Practices for Wiki Usage, Style, and Publication" project (Help:Best Practices) than on this obsolete and incomplete style guide document. I shouldn't have published the style guide in its incomplete form in the first place. Adraeus 06:34, 11 Oct 2005 (EDT)

[edit] Auto-generated titles?

Under "Components" it says that titles are automatically generated. Then why all the previous instruction on composing titles? WendyDespain 20:16, 23 Sep 2005 (EDT)

The article title is automatically generated. For instance, creating an article with the title Wendy Despain results in an article with the automatically generated title "Wendy Despain", which would be located below the article navigation menu. Composition of titles differs from the generation of those titles. Composition concerns how clearly those titles are first formed. You should not repeat the article title as a section heading to name the article as the article is already named with the article title already displayed. Adraeus 22:20, 23 Sep 2005 (EDT)

This isn't clear from how the style guide is currently written. Consider revising. WendyDespain 00:40, 24 Sep 2005 (EDT)

Once the terminology is understood, this is understandable. Adraeus 04:18, 24 Sep 2005 (EDT)

As a help document, the Style Guide should stand on its own. Users shouldn't need to learn a new vocabulary in order for it to make sense. What if you use "Automatically included" instead of "Automatically generated"? That way it doesn't sound like the wiki software makes up titles itself, but that it includes the title which the user generated when naming the page. Come to think of it, in the section about good title style, perhaps a link to a "quickstart" guide would be in order. A section of it that might explain how to create a new page (with the explanation that the name of the page will display as the title of the document). WendyDespain 17:56, 27 Sep 2005 (EDT)

[edit] "Embolden"

Under "Formatting" is the sentence: "Emboldened text is attributed thicker, heavier lines."

I think it should read, "Bold text has thicker, heavier lines." Emboldened is the past tense of a verb - text doesn't actually get braver. Attributed is an unnecessarily long word for a simple concept. WendyDespain 20:16, 23 Sep 2005 (EDT)

My background is graphic design and typography so I used the words that we use in typography. Adraeus 22:20, 23 Sep 2005 (EDT)

Part of my background is in science journalism - making complicated technical information understandable to a wide audience. So I can spot unnecessarily confusing jargon, particularly in documents intended for a wide audience. WendyDespain 00:40, 24 Sep 2005 (EDT)

I see that I still can't make changes directly to this help page. Do you have plans to include these edits? WendyDespain 17:56, 27 Sep 2005 (EDT)

[edit] Recommend against underline

Personally, I think we should recommend nobody ever uses underline. It looks too much like a link. WendyDespain 20:16, 23 Sep 2005 (EDT)

Underlines are useful for bibliographies and other referential sections. Adraeus 22:20, 23 Sep 2005 (EDT)

It's bad user interface in hypertext documents, even in bibliographies and reference sections. 00:40, 24 Sep 2005 (EDT)

Myth. Simply because the medium isn't print does not mean that print standards are suddenly inapplicable and worthless. Adraeus 04:18, 24 Sep 2005 (EDT)

The problem with underlined words in a hypertext context is that from the beginning, hypertext has used underlined text to denote a link. When users see an underlined word, they expect they can click on it and go to a related page - even on a website design like this one that only uses a new color for a linked word, rather than an underline. The underlined link is so pervasive, it is an Internet standard. Underlined words are clickable. When underline is used on a word that is not clickable, it confuses the user. Especially in bibliographies, where users may expect underlined book titles to lead to a page where they can read the book or buy it. If you think all of this is a myth, I'd like to see your references for that debunking. WendyDespain 17:56, 27 Sep 2005 (EDT)

CSS didn't exist when the original underline-style of hyperlinks was applied. Since then, CSS has replaced HTML's style elements, and a new environment more in line with traditional media style is developing. The Internet is far more dynamic and interactive than it was when originally released to the public. We should not continuing using superannuated "Internet standards" that are the result of poor design and bad habit. Humans adapt, and eventually, they'll adapt to the new environment where style and content are separated. Adraeus 06:42, 11 Oct 2005 (EDT)

[edit] Acronyms

In the "Acronym" section, I think it needs to be clarified - what counts as the "first reference" in a hypertext context? Do we have to write out International Game Developer's Association the first time we use it on every page? I think this would only make our content harder to read. There should be some acronyms that are defined in one place that we can use freely. IGDA and SIG being two examples. They need to be spelled out, but not on every page of the wiki. WendyDespain 20:16, 23 Sep 2005 (EDT)

Remember: I used examples in the style manual to demonstrate concepts. Since the wiki is no longer oriented towards developing into a knowledge repository, there is no need to write out commonly used acronyms (e.g., IGDA, SIG) by IGDA members. In addition, what IGDA means is obvious given the logo. There are many other acronyms which should be written out when first referenced in an article. These acronyms are usually created by individuals for some purpose and are not widely recognized. If you feel that there should be a glossary (and there should be), create a glossary. Adraeus 22:20, 23 Sep 2005 (EDT)

The example currently on the style guide illustrates that every time we use "IGDA" on a page we should spell it all out the first time - whether that's what you intended your example to illustrate or not. I suggest using a different example to make it more clear. Also, if you don't intend to enforce a section of the style guide, why not remove that section, or edit it so that it's clear how it should be enforced? WendyDespain 00:40, 24 Sep 2005 (EDT)

Also, the introduction mentions that there already is a glossary. I assumed it existed already and didn't want to create a duplicate page. WendyDespain 00:40, 24 Sep 2005 (EDT)

If you see a red link, the article doesn't exist. Adraeus 04:18, 24 Sep 2005 (EDT)

The place where the glossary is mentioned in the introduction (oh, you're using the academic word "abstract" for introduction, aren't you? hrm. that conversation will have to wait I guess) it wasn't a red link. It wasn't a link at all. So I assumed you were building one but hadn't posted it yet, as that's the logical place to provide a link. Also, this is strange, "If you require assistance with locating the glossary, please consult a contributor." The glossary should be one of the easiest pages to find for a newbie and whenever it's mentioned it should be linked - to facilitate easy finding. WendyDespain 17:56, 27 Sep 2005 (EDT)

[edit] Abbreviations

The entire "Abbreviations" section doesn't seem to apply to this wiki. Can you provide a more taylored example? WendyDespain 20:16, 23 Sep 2005 (EDT)

Can you provide me with some abbreviations used in the industry? I would think that business correspondence is similar in all industries. Adraeus 22:20, 23 Sep 2005 (EDT)

In the games industry we are unlikely to be referencing His Royal Highness Prince of anything. Unless it's the Prince of Darkness, but I don't think that would be abreviated. It's mostly words that have turned into jargon like "spec" and "doc." WendyDespain 17:56, 27 Sep 2005 (EDT)

[edit] Compound words

Do we need the section on compound words? I think it's unnecessary and will intimidate new users. In the context of this wiki, users probably won't be getting in flamewars over grammar, and if a question does arrise you've already named the Chicago Manual of Style as the arbiter. WendyDespain 20:16, 23 Sep 2005 (EDT)

There will probably be infighting, as I've experienced such already, when this wiki becomes more popular. Regardless of likelihood, there should be a description of compound words and proper hyphenation in the style manual if only for users to fall back upon. Adraeus 22:20, 23 Sep 2005 (EDT)

It's possible to quash a wiki community completely by applying advanced user management to fledgeling communitites. Unless this disease rears its head, the cure could kill the host. It's insulting to lecture users on introductory grammar without provocation. Treating expert game developers like fourth-graders will foster only animosity. Not participation. WendyDespain 00:40, 24 Sep 2005 (EDT)

The style guide is not a lecture. It's a reference. Adraeus 04:18, 24 Sep 2005 (EDT)

Right now, it reads like a lecture. WendyDespain 17:56, 27 Sep 2005 (EDT)

[edit] Hyphenation

Ditto the section on hyphens and dashes. I think this space in the style guide would be better put to use encouraging participation and addressing specific questions such as when to put pages into directories and when to link to an existing page vs. when to create a new one on a similar topic. WendyDespain 20:16, 23 Sep 2005 (EDT)

In these early stages of the wiki's lifecycle, forward thinking is necessary. While the style guide exists to encourage proper formatting, style, punctuation, consistency throughout the wiki, the style guide also exists to form a foundation upon which disputes about style can be efficiently settled. Elonka Dunin has been working on a usage guide, and I intend to revamp the usage guide to be more consistent with the style and policy guide as well as more extensive. By the way, a style guide is more flexibly than a policy manual. Policies are essentially dictatorial decrees of proper behavior whereas the style guide acts as a guide to professional style standards. The superiority of substantive content over superficial appearance is recognized, and I expect users to apply the style guide only when required for the improvement of an article or the wiki. If certain portions of the style guide are deemed unneccessary for certain articles or sections, then that's fine... until someone else comes along who finds a necessity. Adraeus 22:20, 23 Sep 2005 (EDT)

This is not how the introduction to the style guide reads. It reads as official standards which will be enforced if ignored. It's really very intimidating, and makes me feel like I'm taking my life into my hands every time I create a bulleted list. I agree that a framework needs to be in place so that submissions to the wiki won't become a tangled mess. But I do think we need to be clear about our process and meaning. WendyDespain 00:40, 24 Sep 2005 (EDT)

I don't see how that interpretation is even possible. The terms used to indicate the flexibility of the style guide are as follows: "guide", "authoritative", "guidelines", "principles", "framework", and "recommends". A guide suggests a direction in which you may decide to go (e.g., the IGDA.) Authority is that to which you appeal for resolution (e.g., a producer.) Guidelines are not rules (e.g., code of conduct.) Principles are basic generalizations accepted as true that are used to aid decision-making (e.g., principles of game design.) A framework is a hypothesis (e.g., a constitution.) Recommendations, which do not come at the edge of a sword, are courses of action considered advisable or desirable (e.g., book recommendations.) As I've said time and time again, only a portion of the style guide is online, the style guide is incomplete, and the wiki lacks a formalized vision and mission. You are spending too much time on material that is in-development when you could be contributing substantive content to the Writers SIG article. Adraeus 04:18, 24 Sep 2005 (EDT)

"Guide" sounds flexible. "Authoritative" does not (your producer can fire you for insubordination). "Principles" does not (principles are used to pass judgement). "Framework" does not (if you're not within the framework, you're off in the middle of nowhere. Being unconstitutional is a bad, bad thing). Words have connotations as well as denotations. We need to be aware of both, especially as we encourage new users to have a happy experience in our wiki. I feel a lot of ownership of this wiki - as I think all users should. I am concerned about playing well with others here, and following guidelines. I don't want to cause trouble. I do want to be involved. I am putting off some work in the Writers SIG section because I see no sense in proceeding there until I understand how best that work can be done. Nobody wants to have to re-do 20 pages that could have been done correctly in the first place, if only the user understood what was wanted. WendyDespain 17:56, 27 Sep 2005 (EDT)

Your interpretations of the words you mentioned are likely not the norm. All the words I use are chosen using their literal definitions.

"authoritative": sanctioned by established authority; of recognized authority or excellence. [2]

The style guide and policy manual are authoritative works because a) these works are approved by Jason Della Rocca (authority) and b) these works support principles of excellence in publication and communication.

"principle": a basic generalization that is accepted as true and that can be used as a basis for reasoning or conduct; a rule or standard especially of good behavior. [3]

Principles of excellence are standards that can be applied; however, application of principles is not a requirement for excellence. In fact, actions taken that disregard conventional wisdom often produce excellent results. A "principle" is a flimsy and subjective ideal, but principles are not beliefs; they can change, and they can be responsibly ignored without the violator being prosecuted for not adhering to "principles". Principles are not rules so we are not governed by principles.

"framework": a hypothetical description of a complex entity or process. [4]

Authoritative principles combine to establish a framework, or hypothetical model, for a certain result. In our case, excellence in publication encourages and influences excellence in communication. Our ultimate objective: to communicate effectively. A framework can also be likened to a foundation, where content development is supported.

As I mentioned before, the style guide and policy manual are reference works. Help:Editing and IGDAwiki:Quick Start Guide are the newbie-friendly devices to help new users familiarize themselves with the basics. I am well-aware of definitional variation. If my goal was to create politically correct documentation that uses "alternative" terminology to avoid causing "harm" or "offense" to a reader, I probably wouldn't exist. Developing a definitionally correct vocabulary is an individual responsibility. If definitional standards exist, I will use them since that is the most effective method for increasing and maintaining the likeliness of a correct interpretation of that which is written.

As I also mentioned before, the style guide and policy manual are in-development. I am considering combining these documents into a "Best Practices for Wiki Usage, Style, and Publication" reference work. Actually, I think that's what I'll do, but I'm not going to change my writing style to "politically correct". As I planned for the style guide and policy manual, the Best Practices document will be published to this wiki and left unprotected to allow minor changes. Significant changes will, of course, require either approval by Jason or myself.

Until that document is completed, I suggest you just continue contributing to the wiki. Be professional, and I won't be swamped with renaming articles to adhere to future naming conventions (e.g., "GWSIG *" => "Game Writers SIG/*") or deleting trash and spam. Once this document is completed, there will probably be a lot more users to help you apply the best practices to articles to which you contribute. Don't think "I'm going to have to redo 20 pages alone." I'm here, and I'm sure there others willing to help minimize the workload. Adraeus 06:04, 11 Oct 2005 (EDT)