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