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
>