After recent changes should the design documents be updated?

[MikkoM]

There have been a lot of changes recently especially with the meter system and with the focus settings, but the design documents still talk about secondary foci and construction meter`s relationship with growth. And if the design documents are supposed to be “the game design of FreeOrion” this seems a bit problematic. Now this probably isn`t a too big of a problem for the old members, but might be quite confusing for a newcomer who thinks that he/she can get a good idea of FreeOrion`s current game design by reading through those documents. So it might be a good idea to update the design documents so that they contain the recent major changes in game design.

[pd]

Personally, I can live with outdated documentation, as long as features get added. Geoff is basically running the whole show on his own at this point. Do you volunteer to do the changes yourself?

[MikkoM]

Geoff is basically running the whole show on his own at this point. Do you volunteer to do the changes yourself?

Well like you said as Geoff is basically running the whole show and is the author of most, if not all, of those changes it might be best if it would also be he who would make the document changes. This isn`t of course a very high priority issue and could be done when/if there is time, but it might make the FreeOrion game design more clear to everyone and possibly at least in the long run reduce the amount of confused people on the forums. (Assuming of course that those people read the design documents through.) I might of course try to make the changes myself, but since there have been quite many changes recently I am not even sure if I am up to date with all of them myself.

[Geoff the Medio]

Updating the design documents is on my to do list... It's not a high priority though. Someone else taking on the task would be helpful. Even if they're not completely aware of all the changes that have been discussed, they can make known changes.

[MikkoM]

Someone else taking on the task would be helpful. Even if they're not completely aware of all the changes that have been discussed, they can make known changes.

Well I can try to make some changes in the near future, but can`t guarantee that they will be good enough to warrant a permanent place in the design documents, as I am not too familiar with how the game engine actually works under the UI. Alternatively I could just post some change suggestions to this thread to get them approved first, but don`t really know if that would be helpful at all.

[Geoff the Medio]

Well I can try to make some changes in the near future, but can`t guarantee that they will be good enough to warrant a permanent place in the design documents, as I am not too familiar with how the game engine actually works under the UI. Alternatively I could just post some change suggestions to this thread to get them approved first, but don`t really know if that would be helpful at all.

Whichever is fine.

You should probably be modifying a new version of the design documents for v0.4 rather than editing the v0.3 document. Much of the v0.3 stuff could be prepended to the v0.4 design pad to flush it out into a full v0.4 design document.

However, much of the v0.3 document outlines details of implementation (ie. how the engine actually works) that aren't really necessary for a design document. Much of the specifics of content are things that need to be tweaked regularly or fully replaced based on balance choices (eg. game start conditions, specific planet/star types that should exist). Similarly, code or data implementation details don't need to be in a design document (eg. specifying that tables will be used to look up certain numbers, details of how universe generation is implemented). Nothing about the details of the UI needs to be in the game design document either...

[MikkoM]

You should probably be modifying a new version of the design documents for v0.4 rather than editing the v0.3 document. Much of the v0.3 stuff could be prepended to the v0.4 design pad to flush it out into a full v0.4 design document.

And does "a new version of the design documents for v0.4" mean this page:

http://www.freeorion.org/index.php/0.4_Design_Pad

... or an entirely new wikipage that I create and then copy the contents of the 0.4 Design Pad to it?

I am also wondering, if it would be an easier overall process to post the proposed changes first to this (or some other) thread, where they could be reviewed and approved, and only after that go and edit the design documents themselves. The reason behind this is that if there will be a need for similar changes in the future and these changes are written by numerous different people and they are of varying quality, the design documents might quite easily become messy and not very informative. And it would be nice to have clear and informative design documents also in the future, which could then be used to instruct new people about FreeOrion`s game design as well as remind the old members about how something was done. Anyway isn`t a similar preapproval process already used with the code contributions?

[Geoff the Medio]

And does "a new version of the design documents for v0.4" mean this page:

http://www.freeorion.org/index.php/0.4_Design_Pad

... or an entirely new wikipage that I create and then copy the contents of the 0.4 Design Pad to it?

Either. The main point is that you shouldn't modify the v0.3 design document. Start with a separate page if you're worried about doing something wrong.

I am also wondering, if it would be an easier overall process to post the proposed changes first to this (or some other) thread, where they could be reviewed and approved, and only after that go and edit the design documents themselves.

That sounds like more work, not easier overall...

The reason behind this is that if there will be a need for similar changes in the future and these changes are written by numerous different people and they are of varying quality, the design documents might quite easily become messy and not very informative.

If we have that problem, we can deal with it. It's probably not worth worrying about preemptively.

Anyway isn`t a similar preapproval process already used with the code contributions?

Yes, for new code contributors.

Code changes can create problems for anyone else using the code, though, and the requirements for acceptable code (arguably) more stringent. Poorly written documentation changes are better than none, generally, but poorly written code is often worse than none. Fixing documentation is probably easier as well.