Several Questions: Documentation; New event?

[Angelo]

Dear readers,

first of all I was wondering, that event PGD Annual, is it 1 time in the year?
If so, I would like to sign myself up for the year 2008 :) *You got a new team in this event!!!*

And second, does anyone have any kind of documentation for me?
I will explain it clearly:

A documentation that is needed to make your plan, just like the article of JDarling.
I would just like to have an example, maybe a very old project of you?
If so, could you post here a link or contact me or whatever?

Thanks in advance,

Angelo.

[Angelo]

The project Plan should be something like this, right?

http://www.streetglowgame.nl/documentation/TunerZ_project_plan.pdf

[WILL]

Hi Angelo,

To answer your first question, the PGD Annual is a yearly event, hence the name. ;) Unfortunately the competition portion of the event has come and gone so you will have to wait for the registration announcement to come out which has usually been in the last few months of the year. However next year might be totally different.

I know Dom (aka savage) though, he'll host another one. :)

If you are interested in some of the games or information on past and current you can visit the Competitions section (http://www.pascalgamedevelopment.com/competitions.php) of the site. (Sorry no menu button yet, it's on my 'to do' list.)

Or you can read all about both the PGD Annual and the history of the site in the current issue of Dev.Mag (http://www.devmag.org.za/viewissue.jsp?id=18)! I highly recommend giving it a read through.


As for the project plan request for this year... we simply needed something to show for all the interested parties and to have something concrete to start everyone off on the right foot. A 'real' design document would be a bit more formal. However there is no one way to write one up.

Jeremy's article does a good job of explaining what you need to outline a fully formal design document and a few other documents as well however not all of these are required all the time in all cases.

[Traveler]

If your interest lies in competitions in general, there's a host of other competitions held by various gamedevelopment sites. For instanceGamedev.net (http://www.gamedev.net) has it's yearly Four Elements competition, which is usually held around this time.

[jdarling]

You can download the design doc for my entry this year at: http://www.eonclash.com/JumpStart/v4/PGD07/Rezolver%20Design%20Doc.doc

The same format was used by quite a number of the teams, and some place I have another thread about the particular template that I created. Its not perfect, and as WILL said not everything is necessary, but it does cover most of what should be in small or hurried projects.

Hopefully, some time soon I'll have time to start on articles 2 and 3. So stay tuned for more useless information about documentation and marketing practices :)

[Angelo]

Thanks jdarling, this was exactly what I was searching for.

Ghehe, when I read your document, I'd guess you were from the USA.
I took a look at the forum... and you are from the usa!!!

I do not want to be rude, because in overall it is a good document, but it is a typical american document.
Somehow Americans have the feeling to say things in 20 pages, what I would be able to say in 1 page.
For example of course, and I don't mean this as an offense, but it's just funny that I can locate you while reading your document :P

Take for example the documentation of UPS, how to write the xml script that auto-updates your order to UPS.
There is a documentation for it with 120 pages!!!

But again, thanks, these are the guidelines for me.

[jasonf]

I used JDarling's document and found it to be just the job. There were some parts which I deleted as overkill, but the rest of it was great.

I didn't find anything "American" about it, I thought it was very professional.

At my company, we have documentation standards which would make JDarling's document look like a postage stamp or childrens' bedtime story in comparison. Some of the are overkill IMHO, but there're all there for a reason, whether I understand this or not.

When you're dealing with other parties, it doesn't hurt to explain yourself very clearly indeed from as many different points of view as possible because if there's a misunderstanding and the other party makes a mistake, it can be very costly.

At first glance, it may appear that Games don't fall into this expensive corporate scenario, but that would be a very inaccurate assumption. Games require a lot more co-ordination and sharing of ideas than a lot of commercial projects.. If these ideas aren't communicated properly then mistakes are make which costs time, money and in some cases, the deadline and ultimately, the company.

[Angelo]

Yes, you are right Jason.

But the thing you said, "overkill", that is typical American.
Well, it's called like that at my place.

Indeed, the document is very professional and I will be using it as a standard, with permission from JDarling of course?!

And to clear up the words "typical American", I mean for example this:
A table and after that a diagram.
Another example: "Roman Numerals from 1 to 11 are".
I think this is overkill, but hey, it's only my opinion ;)

The company I work for hasn't got loads of documents (its only web and a very very very tiny bit of application development tho), so maybe it's just that I am not used to it.
Otherwise it could be the lack of professionality at my side.

[Robert Kosek]

Well, considering that there are probably more people here that aren't American than there are Americans, your statement is inaccurate. My code license is ~25 lines long and covers everything; the MPL or GPL are huge and written by lawyers all over the world.

I'll be tactful and not classify the folks I see like you have done.

If you want to do anything with game design or programing learn from the professionals that a game "bible" for your project is essential because everything is decided. There's no true disputation, questioning what goes where, or if something is really needed. The only question becomes "do we have the time/money to keep this feature?"

I work in the software industry as well, and we work with a web interface embedded in a custom server. Let me tell you that not having clear documentation and an understandable guide to our developmental path is killing us. But no one wants to admit it, and I'm just the contractor guy.

If you will make a serious game with a decent amount of content and programming to it and are working with others then you have no choice but to write a detailed design document. And detailed doesn't mean wordy or terse, it means detailed enough. I can imagine the action of a gun if you tell me it is lever action because I already know it, so leave out the worthless scrap and really describe things. Otherwise the team will flounder and you'll be lucky to get anything out the door at all.

[jdarling]

See, from my point of view its the Brits that overkill our documents :). Recently a document that for one of our US customers would have been around 100 pages jumped to over 400 pages due to the level of detail that that client wanted within the document.

Though, saying its a British thing is incorrect as well, its more of a corporate thing. The larger the company "wants to be" the more they bloat a document to make it look important. Large companies that know they are large typically want the smallest document they can get their hands on :). MS is a perfect example, too many times I've been told "can we shorten this at all?"

So, no offense taken on any comments. In fact, I did my best to get the doc down to the least amount of sections for the broadest audience I could. Thus it should be very customizable. There are sections that I (personally) feel should be in all design documents, while others will say that they aren't necessary.

[Angelo]

The same format was used by quite a number of the teams, and some place I have another thread about the particular template that I created

You made a template? May I be so rude to ask you if I may use it? And if so, where can I get it?


Hopefully, some time soon I'll have time to start on articles 2 and 3. So stay tuned for more useless information about documentation and marketing practices

I can't wait, since I find this very usefull information.
Most people underestimate such things and start a project with only an idea in their mind, people like me...
But I want to do it professional now, so any help/article will be helpfull.

As reaction on the event (sorry read over it), it is really really really stupid that I didn't notice the name "PGD Annual"...
So sorry for asking such a stupid question.

No I do not want to do any competition other than the PGD competitions.
I will be patient and will wait for the new submissions.

Now I came up with some other questions, may I?

#1. Is there also a Internal Document, with i.e. documents for when what should be done without releasing anything to the press?

#2. In a big company (I work for a tiny company) how do you test your code? For example you are doing the physics of an engine, and someone else does the graphics. You can not test your part without the other part of the engine, how do you solve such things?

Thanks for answering all my questions, I know I can be a pain in the ass...
But I just want as much information as possible, thanks in advance.


Sorry, I really didn't mean it as an attack, and I am sorry if I hurt anyone with it.
And I have edited my previous post, so maybe it is more clear now what I meant?

JSoftware, may I use your documents?


Again, sorry, maybe I should have said it with other words...

[Angelo]

Oh I found your template.

Which is more professional?
The spongebob thingie or the rezolver?

Because, I was talking about the Rezolver documentation all the time...

[jdarling]

Template download (the one I posted for this years compo):http://www.eonclash.com/DocTemplates/Game Design Document (Template).doc

As for documents and everything else. As I said in my article (some place), yes for our clients we build out multiple documents each with a very specific purpose. Some examples:

Requirements Matrix - Excel spreadsheet listing ALL of the requirements and alternate requirements along with approval status and signoff person.
Requirements Document - A MS Word Doc file that references the above document, this gives greater detail to the requirements and how they should be implemented.
Storyboard - If needed this is a simple picture that shows the basic high level flow of the product along with the creative concepts to help the client decide what concept/workflow they desire.
Design Document - Pretty much built from the first two above and as described, contains the actual design implementation features as well as incorporates the storyboard if one was built. This document also contains "Wire frames" and process/workflows to show how data, users, and everything else will interact and move through the system.
Test Document - Build from the Design Document and Requirements to say how the product will be tested and what platforms it will be tested on. This document gives step by step instructions with pass/fail conditions that any tester can take and test the product from.

This list can get bigger if we have User Experience Architects involved as they will build their documentation as well.

I don't build all of the documents above for all projects, in fact we don't even use all sections of each document above for all projects. We custom tailor the documents and the contents to the client/project need. Multiples of each document are created for projects that contain multiple products when necessary.

In a large corporate environment the "Press Documents" are none of the above. There are very specialized individuals that take the above and get the information ready for release. Some of the documents above (Design Document as an example) never get released to the client either.

Multiple integration points within a large product will be spelled out VERY clearly. Yes, specific test scenarios are built out for those integration points so that they may be tested separate and integrated. We may also create very specialized test applications or suites when needed.

I think that that is probably enough of information overload for a bit. If you chew it over you will see that at the corporate level you have to be flexible, but at the same time, you have to be able to over document :).

[WILL]

I guess I should add that once I have some more time I'll be adding a list of game plans/design docs for this year's teams at the bottom of the details page of this year's competition.

It should make for a somewhat interesting, if not useful, source of information.