gamedevlists-design — List for discussing game development design

RE: [GD-Design] Design Documents

[Sellers, M. <mse...@or...>]

Albert Reed wrote:
> We use Word for our non-technical design documentation and 
> have yet to really run into problems. However, for the most 
> part only one person ever edits a given section of the design 
> document at a time. Everyone contributes ideas, and someone 
> who's a good writer sticks them into the doc. We have it 
> broken into several sections and then exported into HTML. The 
> doc right now is about 70 pages. To keep people up-to-date we 
> just paste changes onto the homepage of our internal web 
> server for all to read.

I should add given my earlier comments that we use "Word + Perforce" not
just word by itself.  Word is great for docs, and Perforce (or your favorite
source control tool) manages the versioning/branching/merging issue.  We
keep our docs accessible from an internal web site as well, so you don't
have to check them out to view them or anything.  

> The reason we went with this solution was simplicity. If you 
> don't need to have multiple people editing the same section 
> of the document at the same time, then you won't run into any 
> problems. Saving as HTML and putting it onto a web server 
> works great for us, since it's super-easy for programmers to 
> look up the information they need just by browsing around on 
> our internal server. There's no setup time, and file->save 
> as... Is about as easy as it gets.

Yep.  And simplicity wins out *big* in areas like this.  Tools that are
way-cool but at all cumbersome to use just won't get used; people will find
it easier to circumvent the tools instead.  (FWIW, ours is a large team
project too, so this doesn't seem to have issues of scaling to support a
large project or a large team.)  

Mike Sellers

RE: [GD-Design] Design Documents

[Sellers, M. <mse...@or...>]

JC wrote:
> Kent Quirk <ken...@co...> wrote:
> 
> > I have to reiterate: Word is a very bad choice for what you're trying 
> > to do. It's way too heavyweight, gives the users too much control 
> > where you don't want them to have it. I have seen it many times, and 
> > heard of it many more times -- if you use Word as your spec creation 
> > tool, you end up adapting your processes to cope with its weaknesses. 
> > It's just a terrible way to create structured documents.
> 
> Agreed.  Either SGML (DocBook?) or (La)TeX would seem the 
> obvious choices and are the canonical solutions to this problem.

It depends what you're trying to do.  For us, Word works well enough for
most design and technical docs, and hasn't caused us to compromise our
processes or design.  We can save docs in HTML format for online viewing,
and back in nicely formatted Word format for printing.  Using more exotic
tools would just be a distraction from trying to get the *game* done.  FWIW,
I don't know anyone using SGML or LaTeX -- are people really still using
these?

Mike Sellers

Re: [GD-Design] Design Documents

[J C L. <cl...@ka...>]

On Wed, 07 Nov 2001 12:38:38 -0500 
Kent Quirk <ken...@co...> wrote:

> I have to reiterate: Word is a very bad choice for what you're
> trying to do. It's way too heavyweight, gives the users too much
> control where you don't want them to have it. I have seen it many
> times, and heard of it many more times -- if you use Word as your
> spec creation tool, you end up adapting your processes to cope
> with its weaknesses. It's just a terrible way to create structured
> documents.

Agreed.  Either SGML (DocBook?) or (La)TeX would seem the obvious
choices and are the canonical solutions to this problem.

-- 
J C Lawrence
---------(*)                Satan, oscillate my metallic sonatas.
cl...@ka...               He lived as a devil, eh?
http://www.kanga.nu/~claw/  Evil is a name of a foeman, as I live.

Re: [GD-Design] Design Documents

[Corrinne Y. <cor...@sp...>]

----- Original Message -----
From: "Kent Quirk" <ken...@co...>
To: <gam...@li...>
Cc: <ph...@me...>
Sent: Wednesday, November 07, 2001 11:38 AM
Subject: Re: [GD-Design] Design Documents


> But again, I'd recommend a simple collection of XML formats and a text
> editor. The document doesn't have to be a lot more complicated than
> something in HTML:
>
> <title>MyTitle</title>
> <subtitle>First section</subtitle>
> <body>Here's the first part of the body. It can go on for a
> while.</body>
>
> A decent text editor (check out EditPlus) will let you put these things
> in nearly automatically. And XMLSpy may actually go a lot farther than
> that, but I haven't used it for the last couple of revisions.

-- Out of curiosity, is EditPlus has HTML features not in Visual C / Visual
Developer that is helpful to design documentation?

-- I edit HTML just as another text window while I am writing code inside
the development environment.

-- Game Design becomes -> Comments and Structures and Placeholder Functions
becomes -> Source Code becomes -> Executable.

-- In fact, Game Design just seems naturally to become the Technical Design
(structural) of the Game Modules of the Source Code.

-- Sometimes it goes the other way, source code becomes comments. Comments
becomes HTML text file. HTML text file becomes documentation or design.

-- Not that Visual Developer is the greatest text or code editor I had ever
use (that would be the Brief type editors). But it is much more tightly
integrated into DirectX and Direct3D which I use heavily. Since I have to
use VD for DX and D3D, I try to do everything else inside it too.

-- I try not to let "game design" sit in HTML too long before prototyping it
into the code.

-- It is funny I used think that I like programming a lot more than many
things and therefore it would be easy for source code to outpace the design.
As it turns out, it is a really easy job to write a "design sentence", and
then a couple more days (average, sometimes shorter, sometimes longer) of
"source code" to actually implement a design phrase.

-- Coding definitely requires more time and effort than design. :) It takes
a lot of discipline to overcode and to underdesign, even for a programmer.

-- Though it can be said that part of the coding programming and
implementation is in fact design (i.e., not technology) work.

RE: [GD-Design] Design Documents

[Albert R. <al...@de...>]

We use Word for our non-technical design documentation and have yet to
really run into problems. However, for the most part only one person
ever edits a given section of the design document at a time. Everyone
contributes ideas, and someone who's a good writer sticks them into the
doc. We have it broken into several sections and then exported into
HTML. The doc right now is about 70 pages. To keep people up-to-date we
just paste changes onto the homepage of our internal web server for all
to read.

The reason we went with this solution was simplicity. If you don't need
to have multiple people editing the same section of the document at the
same time, then you won't run into any problems. Saving as HTML and
putting it onto a web server works great for us, since it's super-easy
for programmers to look up the information they need just by browsing
around on our internal server. There's no setup time, and file->save
as... Is about as easy as it gets.

We use a company style-sheet which is applied to each document so the
webpages come out looking pretty. Printing from Word's HTML editor has
worked fine for us. Again, this solution hasn't been the most elegant,
and probably wouldn't work for a large team of designers, but overall,
it's served us very well and wasted no valuable time in setup.

For technical documentation we just have a big pile of Word docs in a
folder on the web-server and compliment that with a Java-Doc type
program. Messy, but it works.

-Al

Re: [GD-Design] Design Documents

[Kent Q. <ken...@co...>]

I have to reiterate: Word is a very bad choice for what you're trying to
do. It's way too heavyweight, gives the users too much control where you
don't want them to have it. I have seen it many times, and heard of it
many more times -- if you use Word as your spec creation tool, you end
up adapting your processes to cope with its weaknesses. It's just a
terrible way to create structured documents.

You want STRUCTURE for a collection of related documents. Formatting can
come later and be automatic.

FrameMaker will let you create structured documents, if you absolutely
must write documents with all the formatting in front of your nose.
Lotus Notes will impose the structure while you're creating the
document, so you can't break it.

But again, I'd recommend a simple collection of XML formats and a text
editor. The document doesn't have to be a lot more complicated than
something in HTML:

<title>MyTitle</title>
<subtitle>First section</subtitle>
<body>Here's the first part of the body. It can go on for a
while.</body>

A decent text editor (check out EditPlus) will let you put these things
in nearly automatically. And XMLSpy may actually go a lot farther than
that, but I haven't used it for the last couple of revisions.


And in response to another query, you probably have created tools for
art, testing, development, and production. Why not documentation?
They're easy to build.

	Kent



Philip Harris wrote:
> 
> > While not particularly difficult, it could still take some time to
> > develop something worthwhile. Do you guys think it's worth it to write
> > custom tools for documentation management, or do most of you prefer to
> > use standard tools such as JavaDoc or plain old Word?
> 
> Personally I'd prefer to see an off the shelf solution, preferably Word
> because people know it. I think that's probably too optimistic though :)
> 
> If there was a very strong Word to HTML convertor then that might be
> suitable, something that would split our docs into a series of pages and add
> cross referencing would be ideal. Anyone know if such a thing exists?
> 
> Phil
> 
> _______________________________________________
> Gamedevlists-design mailing list
> Gam...@li...
> https://lists.sourceforge.net/lists/listinfo/gamedevlists-design

-- 
-----------------------------------------------------------------------
Kent Quirk                   | MindRover: "Astonishingly creative."
Game Architect               | Check it out!
ken...@co...      | http://www.mindrover.com/
_____________________________|_________________________________________

RE: [GD-Design] Design Documents

[Philip H. <ph...@me...>]

> With Office XP (I don't think it's in the 2000 version), you can save your
> document in 'filtered html'. It saves an optimized version of the
> document,
> for release purpose, then your file is shorter (then faster for loading).

That might be a start. Perhaps some Word macros would provide the rest of
the formating.

Phil

Re: [GD-Design] Design Documents

[Loic B. <loi...@wa...>]

With Office XP (I don't think it's in the 2000 version), you can save your
document in 'filtered html'. It saves an optimized version of the document,
for release purpose, then your file is shorter (then faster for loading).
For the splitting, I can't see any other way than doing it 'by hand'.

Loic

----- Original Message -----
From: "Philip Harris" <ph...@me...>
To: <gam...@li...>
Sent: Wednesday, November 07, 2001 4:53 PM
Subject: RE: [GD-Design] Design Documents


> > While not particularly difficult, it could still take some time to
> > develop something worthwhile. Do you guys think it's worth it to write
> > custom tools for documentation management, or do most of you prefer to
> > use standard tools such as JavaDoc or plain old Word?
>
> Personally I'd prefer to see an off the shelf solution, preferably Word
> because people know it. I think that's probably too optimistic though :)
>
> If there was a very strong Word to HTML convertor then that might be
> suitable, something that would split our docs into a series of pages and
add
> cross referencing would be ideal. Anyone know if such a thing exists?
>
> Phil
>
>
> _______________________________________________
> Gamedevlists-design mailing list
> Gam...@li...
> https://lists.sourceforge.net/lists/listinfo/gamedevlists-design

[GD-Design] Re: Design Documents

[Daniel C. <dan...@an...>]

This is more of a software development generic response, though it seems
applicable to games as well.

A design doc is heavily dependent on the type of organization.  I tend to
use design documents to communicate key ideas and get people excited about
various concepts. Some organizations have great mechanisms for
communication.  These tend to be bogged down by heavy design docs.  Other
organizations have poor communication.  In these cases, a detailed design
doc can be a critical crutch to getting the game finished.

First off I'd split up the terms 'design document' and 'art bible'.  An art
bible is full of pictures and concepts to help artists. Some folks include
this in the definition of 'design doc' but I find it often confuses the
issue.  A design document is the list of rules and systems needed to make
the game mechanics function. It includes UI, reward systems, and perhaps
even plot points. :-)

I've done big design docs and small ones for games and tools.  These days, I
lean towards lightweight design and development processes. We use a
variation of XP (extreme programming) that involves a database of 'feature
cards'.  Each 3 week iteration involves the programming of a few feature
cards.

The wacky part. Each feature card has at most a short paragraph or two of
text. The rest of the design is fleshed out with constant conversations
between the designer and the programmers.

This has a couple of benefits:
- Avoids massive time spent on upfront design of a unproven complex system
that will probably be reworked anyway during user testing.
- People read the design.  How many developers in your company read and
understand 100% of the 300 page design documents?  Every developer
understands new features because the feature cards keep it short, sweet, and
manageable.  And we talk.
- You can react quickly to new discoveries, or changes in focus by simply
adding a new feature card. There is no need to rework a giant doc.

The downside:
- If your publisher doesn't trust your abilities, then you don't have a
massive 'Design Tome' to placate them. :-)

Daniel Cook

-----Original Message-----
From: gam...@li...
[mailto:gam...@li...]On Behalf Of
Sellers, Mike
Sent: Tuesday, November 06, 2001 8:33 AM
To: 'gam...@li...'
Subject: RE: [GD-Design] Design Documents


Matt Newport wrote:
> How long and how detailed are people's design docs generally?
> I personally feel that our design docs could do with being a
> little longer and more in depth but I don't know how they
> compare to those used elsewhere in the industry. I read in
> the Deus Ex post mortem that their design doc ran to hundreds
> of pages, which is rather more detail than we have in ours...

Design docs can easily be hundreds of pages, but I'm not sure they have to
be.  That's like asking how long a novel is -- it's as long as you need to
tell the story.  A design doc serves several purposes, including selling the
design and memorializing it (so you'll remember that incredible idea in
context six weeks from now).  I've seen design docs with too little
high-level design: what's this about, why is it fun, what's the player's
experience, how does this fit together, etc.; and ones with too little
low-level design: what are the pieces, how does movement work, what's the
overall UI like, etc.  The question of when to leave off with the low-level
design and get into implementation is a tough one, but generally I'd say
sooner than later.  Iterate, try it out, and then write it down.  If you've
done the high-level design right, you'll be able to focus on the areas you
need to iterate on a lot more quickly and effectively.

But honestly, this is all still seat-of-the-pants stuff.  I don't know
*anyone* who has a sure-fire design documentation methodology.

Mike Sellers

_______________________________________________
Gamedevlists-design mailing list
Gam...@li...
https://lists.sourceforge.net/lists/listinfo/gamedevlists-design

RE: [GD-Design] Design Documents

[Philip H. <ph...@me...>]

> While not particularly difficult, it could still take some time to
> develop something worthwhile. Do you guys think it's worth it to write
> custom tools for documentation management, or do most of you prefer to
> use standard tools such as JavaDoc or plain old Word?

Personally I'd prefer to see an off the shelf solution, preferably Word
because people know it. I think that's probably too optimistic though :)

If there was a very strong Word to HTML convertor then that might be
suitable, something that would split our docs into a series of pages and add
cross referencing would be ideal. Anyone know if such a thing exists?

Phil

RE: [GD-Design] Design Documents

[Jamie F. <ja...@qu...>]

Leads accepting the importance of it is another problem :)

Jamie


-----Original Message-----
From: gam...@li...
[mailto:gam...@li...]On Behalf Of
Philip Harris
Sent: 07 November 2001 08:41
To: gam...@li...
Subject: RE: [GD-Design] Design Documents


> We bother. Split into components: design, technical, art, etc. 
> Assign owners
> to different components (generally the leads). It's their 
> responsibility to
> keep it up to date (and to decide how up to date is appropriate under the
> circumstances).
 
Sounds sensible, assuming the leads accept the importance of the design.

> Sorry about being terse; finishing demo :)

:)

Phil

_______________________________________________
Gamedevlists-design mailing list
Gam...@li...
https://lists.sourceforge.net/lists/listinfo/gamedevlists-design

RE: [GD-Design] Design Documents

[Tom N. <t.n...@vr...>]

XML is neat, but the hard part is finding a tool that can generate it
for you.

On my previous project, which was written in Java, we used XML/XSL
exactly like Gabor suggested. We only used it for code documentation,
though - not prior design docs. Hence, we could use JavaDox (!= JavaDoc)
to generate the XML from the comments in the code. Turning the XML into
something viewable was a piece of cake thanks to XSL stylesheets.

Similar tools probably exist for C++, but if you want something that
_isn't_ based on code comments (e.g. a game design), you may be out of
luck. Rolling your own tools probably wouldn't be too difficult, though.
Ideally, you'd want something (a macro or plugin) that imports and
exports XML from your favorite text or HTML editor.

While not particularly difficult, it could still take some time to
develop something worthwhile. Do you guys think it's worth it to write
custom tools for documentation management, or do most of you prefer to
use standard tools such as JavaDoc or plain old Word?

- Tom



> -----Original Message-----
> From: gam...@li... 
> [mailto:gam...@li...] On 
> Behalf Of gabor farkas
> Sent: Wednesday, November 07, 2001 10:12
> To: GD Design
> Subject: Re: [GD-Design] Design Documents
> 
> 
> 
> ----- Original Message -----
> From: "Philip Harris" <ph...@me...>
> To: "GD Design" <gam...@li...>
> Sent: Wednesday, November 07, 2001 9:45 AM
> Subject: RE: [GD-Design] Design Documents
> 
> 
> > > To answer to Phil, we're doing many many HTML pages. Each 
> page use a 
> > > CSS we develop to reduce the size of the file, and to always have 
> > > the
> possibility
> > > to modify a given style with automatic change in all the pages. 
> > > We'll maybe use Microsoft Help Workshop to compile the whole into 
> > > one big file, but
> I
> > > dunno if it works with CSS...
> >
> > Have you been able to produce a professional looking 
> printed version 
> > of
> the
> > design docs? I like the idea of the HTML based design doc but there 
> > seems
> to
> > be a problem when it comes to producing versions for publishers etc.
> Getting
> > a decent printed version seems like a lot of work. Having 
> said that I 
> > may just be behind on my HTML theory and really it's a lot more 
> > controllable these days.
> 
> maybe you should use xsl formatting objects...
> so you create your documentation in xml....
> then you transform it automatically with xslt into html
> or use another xsl file ( the xsl-fo ) to tranform it into a 
> .fo file,which can be converted into pdf....
> 
> this way, you only create one data file ( the xml ) with 
> multiple views ( the xsl )...
> 
> 
> but it's possible that this all is just too complex and you 
> can live with word ( + his html export )
> :-)
> 
> 
> gabor
> 
> 
> 
> >
> > > Concerning the update of the doc, well, it's kinda 
> wild...In theory, 
> > > we should update it each time a change is made in the 
> source/design. 
> > > But in practice the change are made when we've finish a big 
> > > coding/design part.
> >
> > How much of the design doc did you produce up front? Or is it being 
> > built
> as
> > the project progresses?
> >
> > > Well, the way we think about concerning documentation is still 
> > > evolving...With VS.Net and its dynamic help, things should be 
> > > different now..We're also working on a "Knowledge Base" 
> tool that'll 
> > > be used to centralize knowledge that everyone have concerning 
> > > one/many projects (brain dumping/sharing tool :) ), but it's in 
> > > progress, not finished yet.
> >
> > Definitely a good idea, we've got plans to put something like this
> together
> > but we've not gotten beyond the "it will have a web 
> interface" stage 
> > yet
> :)
> >
> > Phil
> >
> >
> >
> > _______________________________________________
> > Gamedevlists-design mailing list 
> > Gam...@li...
> > https://lists.sourceforge.net/lists/listinfo/gamedevlists-design
> >
> 
> 
> _______________________________________________
> Gamedevlists-design mailing list 
> Gam...@li...
> https://lists.sourceforge.net/lists/listinfo/gamedevlists-design
> 

Re: [GD-Design] Design Documents

[Loic B. <loi...@wa...>]

Sounds interesting! :)
But I don't know how long it'd take to implement the structure. I'm not a
HTML/XML expert (far from it). Any hints ?

Do you people always use Word for the doc writing ??? Well, I used to do
that too...But I got criticized (harly ;)) by someone who works with me that
it produces too big files (indeed, it does)...
Well, finally, Frontpage is a good way to go, I don't regret the switch.

Loic

----- Original Message -----
From: "gabor farkas" <xl...@po...>
To: "GD Design" <gam...@li...>
Sent: Wednesday, November 07, 2001 10:11 AM
Subject: Re: [GD-Design] Design Documents


>
> ----- Original Message -----
> From: "Philip Harris" <ph...@me...>
> To: "GD Design" <gam...@li...>
> Sent: Wednesday, November 07, 2001 9:45 AM
> Subject: RE: [GD-Design] Design Documents
>
>
> > > To answer to Phil, we're doing many many HTML pages. Each page
> > > use a CSS we
> > > develop to reduce the size of the file, and to always have the
> possibility
> > > to modify a given style with automatic change in all the pages.
> > > We'll maybe
> > > use Microsoft Help Workshop to compile the whole into one big file,
but
> I
> > > dunno if it works with CSS...
> >
> > Have you been able to produce a professional looking printed version of
> the
> > design docs? I like the idea of the HTML based design doc but there
seems
> to
> > be a problem when it comes to producing versions for publishers etc.
> Getting
> > a decent printed version seems like a lot of work. Having said that I
may
> > just be behind on my HTML theory and really it's a lot more controllable
> > these days.
>
> maybe you should use xsl formatting objects...
> so you create your documentation in xml....
> then you transform it automatically with xslt into html
> or use another xsl file ( the xsl-fo ) to tranform it into a .fo
file,which
> can
> be converted into pdf....
>
> this way, you only create one data file ( the xml ) with multiple views (
> the xsl )...
>
>
> but it's possible that this all is just too complex and you can live with
> word ( + his html export )
> :-)
>
>
> gabor

Re: [GD-Design] Design Documents

[Loic B. <loi...@wa...>]

We're originally writing the doc to be viewed from the computed, not really
for a printed version.
However, I think that if we need someday to make a printed version, it'll be
possible to convert the existing one in a reasonable time. As I said before,
we're using Common Style Sheet for the document styles. We've designed many
styles: Header1-6, code sample section, class/structure definition section,
and so on. They're all stored in one css file. Each document page reference
this css file. If we want a printed version, we can develop a new css file
that would implement these styles in a more printed friendly way. We'll
certainly have to change the document structure (no hyperlinks anymore...),
that's the only 'big' job. Well, printed version wasn't a thing we wanted (I
don't think Microsoft has a printed version of the MSDN ;) ).

Concerning the design, it's a major part of the documentation right
now...We're creating a 'preliminary design' document before starting to code
something (which may not be included in the final doc, but only used as a
base for development/doc writing). As we're developping a 'game dev lib' and
not a game itself, we have to document each API/class we're developping. But
from now, mostly the design overviews, references, and samples are written.
A 'method-level reference' documentation is very long/hard to
write/maintain, so we wait a given API to be finished before starting that.
As the sources are well-commented, that do the job for internal use.

For the knowledge base, here's the key features:
- Network distributed database.
- User account system.
- The database is made of categories, and notes.
- Each note can reference one/many categories (for browsing/search). It has
a title, a content (formatted/displayed with a RichEdit control). The
content can store hyperlinks (to pages, pictures, files, ...). Some external
file can be attached to the note.
- Historic of the notes (when a note is being change, the previous version
remained in the database as a previous version).
- User private folders (to store personal notes).
- Intergration with Visual Studio (writting a VS Macro to easily reference a
given note in a source comment).

I won't detail the extra features as we're (as always) late from our
original schedule. And we've gone nuts while discutting about it, so
there're extra features that need lots of time to implement (but that are
very interested).

Loic

----- Original Message -----
From: "Philip Harris" <ph...@me...>
To: "GD Design" <gam...@li...>
Sent: Wednesday, November 07, 2001 9:45 AM
Subject: RE: [GD-Design] Design Documents


> > To answer to Phil, we're doing many many HTML pages. Each page
> > use a CSS we
> > develop to reduce the size of the file, and to always have the
possibility
> > to modify a given style with automatic change in all the pages.
> > We'll maybe
> > use Microsoft Help Workshop to compile the whole into one big file, but
I
> > dunno if it works with CSS...
>
> Have you been able to produce a professional looking printed version of
the
> design docs? I like the idea of the HTML based design doc but there seems
to
> be a problem when it comes to producing versions for publishers etc.
Getting
> a decent printed version seems like a lot of work. Having said that I may
> just be behind on my HTML theory and really it's a lot more controllable
> these days.
>
> > Concerning the update of the doc, well, it's kinda wild...In theory, we
> > should update it each time a change is made in the source/design. But in
> > practice the change are made when we've finish a big coding/design part.
>
> How much of the design doc did you produce up front? Or is it being built
as
> the project progresses?
>
> > Well, the way we think about concerning documentation is still
> > evolving...With VS.Net and its dynamic help, things should be different
> > now..We're also working on a "Knowledge Base" tool that'll be used to
> > centralize knowledge that everyone have concerning one/many
> > projects (brain
> > dumping/sharing tool :) ), but it's in progress, not finished yet.
>
> Definitely a good idea, we've got plans to put something like this
together
> but we've not gotten beyond the "it will have a web interface" stage yet
:)
>
> Phil
>
>
>
> _______________________________________________
> Gamedevlists-design mailing list
> Gam...@li...
> https://lists.sourceforge.net/lists/listinfo/gamedevlists-design

RE: [GD-Design] Design Documents

[Philip H. <ph...@me...>]

> maybe you should use xsl formatting objects...
> so you create your documentation in xml....
> then you transform it automatically with xslt into html
> or use another xsl file ( the xsl-fo ) to tranform it into a .fo
> file,which
> can
> be converted into pdf....
>
> this way, you only create one data file ( the xml ) with multiple views (
> the xsl )...
>
>
> but it's possible that this all is just too complex and you can live with
> word ( + his html export )
> :-)

:) I think you may be right.

I wonder if there is a solution anywhere (outside of the games industry
maybe) for this problem? Games are not the biggest software projects, I
would imagine other industries have even more need for a solution.

Phil

Re: [GD-Design] Design Documents

[gabor f. <xl...@po...>]

----- Original Message -----
From: "Philip Harris" <ph...@me...>
To: "GD Design" <gam...@li...>
Sent: Wednesday, November 07, 2001 9:45 AM
Subject: RE: [GD-Design] Design Documents


> > To answer to Phil, we're doing many many HTML pages. Each page
> > use a CSS we
> > develop to reduce the size of the file, and to always have the
possibility
> > to modify a given style with automatic change in all the pages.
> > We'll maybe
> > use Microsoft Help Workshop to compile the whole into one big file, but
I
> > dunno if it works with CSS...
>
> Have you been able to produce a professional looking printed version of
the
> design docs? I like the idea of the HTML based design doc but there seems
to
> be a problem when it comes to producing versions for publishers etc.
Getting
> a decent printed version seems like a lot of work. Having said that I may
> just be behind on my HTML theory and really it's a lot more controllable
> these days.

maybe you should use xsl formatting objects...
so you create your documentation in xml....
then you transform it automatically with xslt into html
or use another xsl file ( the xsl-fo ) to tranform it into a .fo file,which
can
be converted into pdf....

this way, you only create one data file ( the xml ) with multiple views (
the xsl )...


but it's possible that this all is just too complex and you can live with
word ( + his html export )
:-)


gabor



>
> > Concerning the update of the doc, well, it's kinda wild...In theory, we
> > should update it each time a change is made in the source/design. But in
> > practice the change are made when we've finish a big coding/design part.
>
> How much of the design doc did you produce up front? Or is it being built
as
> the project progresses?
>
> > Well, the way we think about concerning documentation is still
> > evolving...With VS.Net and its dynamic help, things should be different
> > now..We're also working on a "Knowledge Base" tool that'll be used to
> > centralize knowledge that everyone have concerning one/many
> > projects (brain
> > dumping/sharing tool :) ), but it's in progress, not finished yet.
>
> Definitely a good idea, we've got plans to put something like this
together
> but we've not gotten beyond the "it will have a web interface" stage yet
:)
>
> Phil
>
>
>
> _______________________________________________
> Gamedevlists-design mailing list
> Gam...@li...
> https://lists.sourceforge.net/lists/listinfo/gamedevlists-design
>

RE: [GD-Design] Design Documents

[Philip H. <ph...@me...>]

> To answer to Phil, we're doing many many HTML pages. Each page
> use a CSS we
> develop to reduce the size of the file, and to always have the possibility
> to modify a given style with automatic change in all the pages.
> We'll maybe
> use Microsoft Help Workshop to compile the whole into one big file, but I
> dunno if it works with CSS...

Have you been able to produce a professional looking printed version of the
design docs? I like the idea of the HTML based design doc but there seems to
be a problem when it comes to producing versions for publishers etc. Getting
a decent printed version seems like a lot of work. Having said that I may
just be behind on my HTML theory and really it's a lot more controllable
these days.

> Concerning the update of the doc, well, it's kinda wild...In theory, we
> should update it each time a change is made in the source/design. But in
> practice the change are made when we've finish a big coding/design part.

How much of the design doc did you produce up front? Or is it being built as
the project progresses?

> Well, the way we think about concerning documentation is still
> evolving...With VS.Net and its dynamic help, things should be different
> now..We're also working on a "Knowledge Base" tool that'll be used to
> centralize knowledge that everyone have concerning one/many
> projects (brain
> dumping/sharing tool :) ), but it's in progress, not finished yet.

Definitely a good idea, we've got plans to put something like this together
but we've not gotten beyond the "it will have a web interface" stage yet :)

Phil

RE: [GD-Design] Design Documents

[Philip H. <ph...@me...>]

> I work with a combination of teams and management, so I've
> gravitated toward
> multiple Word docs saved as HTML with a central overview doc that
> acts as a
> spine (and includes links to them).  I also use a lot more
> scanned drawings,
> shockwave/director movies, and other graphical methods than I used to (I
> learn slow sometimes).

I tried the HTML from Word route but it seems clumsy. Unless I'm missing
something I ended up with a single very large web page for each doc. The
other option we considered was build the entire doc as a series of web pages
but then a good quality printed version becomes troublesome.

Phil

RE: [GD-Design] Design Documents

[Philip H. <ph...@me...>]

> We have used Lotus Notes to manage databases of related design
> documents, and anyone on the team can maintain them.
>
> If I were starting over right now, I'd probably find a way to use XML to
> create a standard document format, and check the XML docs into a source
> code repository, and use stylesheets to format them for viewing and
> printing.
>
> But in any case, think of your design docs as a database of related
> items, rather than one big document, and impose some standard formatting
> on them, and you'll be a lot happier as the design grows.

That's what we've been considering. Our current design doc is about 250
pages spread over about 10 docs at the moment (and it will be a lot bigger
when it's finished) and it's very unwieldy.

Some sort of web based document is looking a reasonable solution, my only
concern is getting the control for printed versions.

Phil

RE: [GD-Design] Design Documents

[Philip H. <ph...@me...>]

> We bother. Split into components: design, technical, art, etc. 
> Assign owners
> to different components (generally the leads). It's their 
> responsibility to
> keep it up to date (and to decide how up to date is appropriate under the
> circumstances).
 
Sounds sensible, assuming the leads accept the importance of the design.

> Sorry about being terse; finishing demo :)

:)

Phil

RE: [GD-Design] Design Documents

[Loic B. <loi...@wa...>]

Ok, I also have a question concerning this topic! :)

Which program (and which file format) do you people use ??? We were firstly
using Word, but due to the size and the way it generates HTML code, we're
now using Frontpage...There's no grammatical correction ;) and few things
are missing, but it's working great with Common Style Sheet (css).

To answer to Phil, we're doing many many HTML pages. Each page use a CSS we
develop to reduce the size of the file, and to always have the possibility
to modify a given style with automatic change in all the pages. We'll maybe
use Microsoft Help Workshop to compile the whole into one big file, but I
dunno if it works with CSS...
Concerning the update of the doc, well, it's kinda wild...In theory, we
should update it each time a change is made in the source/design. But in
practice the change are made when we've finish a big coding/design part.

Well, the way we think about concerning documentation is still
evolving...With VS.Net and its dynamic help, things should be different
now..We're also working on a "Knowledge Base" tool that'll be used to
centralize knowledge that everyone have concerning one/many projects (brain
dumping/sharing tool :) ), but it's in progress, not finished yet.

Loic

> ----- Original Message -----
> From: "Matthew Newport" <Ma...@re...>
> To: <gam...@li...>
> Sent: Tuesday, November 06, 2001 3:31 PM
> Subject: RE: [GD-Design] Design Documents
>
>
> > I don't really have an answer to your questions but I have one to add
:-)
> >
> > How long and how detailed are people's design docs generally? I
personally
> > feel that our design docs could do with being a little longer and more
in
> > depth but I don't know how they compare to those used elsewhere in the
> > industry. I read in the Deus Ex post mortem that their design doc ran to
> > hundreds of pages, which is rather more detail than we have in ours...
> >
> > Matt.
> >
> > -----Original Message-----
> > From: Philip Harris [mailto:ph...@me...]
> > Sent: 06 November 2001 14:04
> > To: gam...@li...
> > Subject: [GD-Design] Design Documents
> >
> >
> > Two questions about design docs.
> >
> > Firstly, given that for a reasonable size project the design
> > doc is going to
> > exceed several hundred pages, how do people organise them.
> > Single word doc,
> > multiple word docs, HTML?
> >
> > Secondly, are these documents kept up to date and if so how?
> >
> > Or...does nobody bother with them in the first place.
> >
> > Phil
> >
> >
> > _______________________________________________
> > Gamedevlists-design mailing list
> > Gam...@li...
> > https://lists.sourceforge.net/lists/listinfo/gamedevlists-design
> >
>
> _______________________________________________
> Gamedevlists-design mailing list
> Gam...@li...
> https://lists.sourceforge.net/lists/listinfo/gamedevlists-design

RE: [GD-Design] Design Documents

[Sellers, M. <mse...@or...>]

Matt Newport wrote:
> How long and how detailed are people's design docs generally? 
> I personally feel that our design docs could do with being a 
> little longer and more in depth but I don't know how they 
> compare to those used elsewhere in the industry. I read in 
> the Deus Ex post mortem that their design doc ran to hundreds 
> of pages, which is rather more detail than we have in ours...

Design docs can easily be hundreds of pages, but I'm not sure they have to
be.  That's like asking how long a novel is -- it's as long as you need to
tell the story.  A design doc serves several purposes, including selling the
design and memorializing it (so you'll remember that incredible idea in
context six weeks from now).  I've seen design docs with too little
high-level design: what's this about, why is it fun, what's the player's
experience, how does this fit together, etc.; and ones with too little
low-level design: what are the pieces, how does movement work, what's the
overall UI like, etc.  The question of when to leave off with the low-level
design and get into implementation is a tough one, but generally I'd say
sooner than later.  Iterate, try it out, and then write it down.  If you've
done the high-level design right, you'll be able to focus on the areas you
need to iterate on a lot more quickly and effectively.

But honestly, this is all still seat-of-the-pants stuff.  I don't know
*anyone* who has a sure-fire design documentation methodology. 

Mike Sellers

RE: [GD-Design] Design Documents

[Sellers, M. <mse...@or...>]

Phil Harris wrote:
> Firstly, given that for a reasonable size project the design 
> doc is going to exceed several hundred pages, how do people 
> organise them. Single word doc, multiple word docs, HTML?
> 
> Secondly, are these documents kept up to date and if so how?

The answers to these questions depend on who your audiences are: yourself, a
small team, a large team, management, publisher, etc.

I work with a combination of teams and management, so I've gravitated toward
multiple Word docs saved as HTML with a central overview doc that acts as a
spine (and includes links to them).  I also use a lot more scanned drawings,
shockwave/director movies, and other graphical methods than I used to (I
learn slow sometimes).  

And I'd *definitely* advise putting your design docs under source control
immediately.  Our docs also include an initial author, change list,
edited-by, last edit date, etc.  Each also has a "goals" section that
explain what overall gameplay goals this design is intended to meet.
Sometimes just writing out this section will change a design (and it avoids
a lot of "'cause I think it'd be cool" kinds of designs).  We also include a
review date so that we know who has had visibility on the design and when
(though that's not in full use yet).

Mike Sellers

Re: [GD-Design] Design Documents

[Kent Q. <ken...@co...>]

Yeah, what he said -- with one exception. I believe (having managed a
couple of large scale design doc systems) that if you have the right
tools, you can reduce or eliminate the "assign an owner" problem. 

This is NOT to say that you don't assign responsibilities for keeping
specs current, just that I've seen specs fail because the
responsibilities were placed on the wrong people because of problems
with tooling or systems.

Basically, Microsoft Word is an inadequate tool for management of
collections of related documents, or for situations where you want
multiple people to have editorial rights. Just don't go there.

We have used Lotus Notes to manage databases of related design
documents, and anyone on the team can maintain them.

If I were starting over right now, I'd probably find a way to use XML to
create a standard document format, and check the XML docs into a source
code repository, and use stylesheets to format them for viewing and
printing.

But in any case, think of your design docs as a database of related
items, rather than one big document, and impose some standard formatting
on them, and you'll be a lot happier as the design grows.

	Kent

Jamie Fowlston wrote:
> 
> We bother. Split into components: design, technical, art, etc. 
> Assign owners to different components (generally the leads). 
> It's their responsibility to keep it up to date (and to decide 
> how up to date is appropriate under the circumstances).
> 
> Sorry about being terse; finishing demo :)
> 
> Jamie
> 
> -----Original Message-----
> From: gam...@li...
> [mailto:gam...@li...]On Behalf Of
> Philip Harris
> Sent: 06 November 2001 14:04
> To: gam...@li...
> Subject: [GD-Design] Design Documents
> 
> Two questions about design docs.
> 
> Firstly, given that for a reasonable size project the design doc is going to
> exceed several hundred pages, how do people organise them. Single word doc,
> multiple word docs, HTML?
> 
> Secondly, are these documents kept up to date and if so how?
> 
> Or...does nobody bother with them in the first place.
> 
> Phil
> 
> _______________________________________________
> Gamedevlists-design mailing list
> Gam...@li...
> https://lists.sourceforge.net/lists/listinfo/gamedevlists-design
> 
> _______________________________________________
> Gamedevlists-design mailing list
> Gam...@li...
> https://lists.sourceforge.net/lists/listinfo/gamedevlists-design

-- 
-----------------------------------------------------------------------
Kent Quirk                   | MindRover: "Astonishingly creative."
Game Architect               | Check it out!
ken...@co...      | http://www.mindrover.com/
_____________________________|_________________________________________

RE: [GD-Design] Design Documents

[Jamie F. <ja...@qu...>]

I think you need to be careful. A load of document that becomes meaningless
when you start implementing something is bad; but for a designer to know
when that happens takes experience, as they don't generally understand
what's going on under the bonnet (US: hood).

Jamie


-----Original Message-----
From: gam...@li...
[mailto:gam...@li...]On Behalf Of
Matthew Newport
Sent: 06 November 2001 14:32
To: gam...@li...
Subject: RE: [GD-Design] Design Documents


I don't really have an answer to your questions but I have one to add :-)

How long and how detailed are people's design docs generally? I personally
feel that our design docs could do with being a little longer and more in
depth but I don't know how they compare to those used elsewhere in the
industry. I read in the Deus Ex post mortem that their design doc ran to
hundreds of pages, which is rather more detail than we have in ours...

Matt.

> -----Original Message-----
> From: Philip Harris [mailto:ph...@me...]
> Sent: 06 November 2001 14:04
> To: gam...@li...
> Subject: [GD-Design] Design Documents
>
>
> Two questions about design docs.
>
> Firstly, given that for a reasonable size project the design
> doc is going to
> exceed several hundred pages, how do people organise them.
> Single word doc,
> multiple word docs, HTML?
>
> Secondly, are these documents kept up to date and if so how?
>
> Or...does nobody bother with them in the first place.
>
> Phil
>
>
> _______________________________________________
> Gamedevlists-design mailing list
> Gam...@li...
> https://lists.sourceforge.net/lists/listinfo/gamedevlists-design
>

_______________________________________________
Gamedevlists-design mailing list
Gam...@li...
https://lists.sourceforge.net/lists/listinfo/gamedevlists-design