[Freeciv-Dev] Re: Documentation, Usability and Development

[Andrew Sutton <ansutton@xxxxxxx>]

On Tuesday 04 December 2001 07:50 am, Reinier Post wrote:
>   1a same repository, different branch?
>      i don't know of any specific advantages - are there any?
>   1b different CVS repository on cvs.freeciv.org?
>      better from a sysadmin point of view, but you'd still be
>      having the same sysadmins (and they read this list)
>   1c CVS repository on sourceforge or berlios?
>      that way, you'd stick with whatever facilities/policies they offer

i'd vote for sourceforge. it's a fairly comprehensive system and offers 
pretty high availability (with recent exceptions noted :) anyway, they offer 
a pretty good database for bug tracking, feature tracking and task 
management. also, support for documentation ;) and some other nice things 
too. thousands of other projects have had success there. i see no reason why 
freeciv shouldn't.

> 2 What to seed it with?
>
>   1a current Freeciv code
>   1b nothing

two modules: freeciv1 that contains the current module and a placeholder for 
what will eventually become freeciv2 (in whatever form that eventually turns 
into).

> 3 Where to put the documentation?
>   1a in a dedicated corner on www.freeciv.org
>   1b sourceforge/etc

i'd put it on freeciv.org. i think you can link to it from the sf docs 
section. it would be nicer on freeciv. if you're talking about things like 
the user manual, then i'd just include that as a separate product with the 
freeciv project. that would let you get a) the program or b) the user manual 
or c) the strategy guide - if one ever exists.

> 4 What does the documentation look like?
>   Which tools to use to maintain it?

good question. i'm assuming you're talking about internals documentation. i'd 
suggest html. its pretty much universal. as for an editing tool... hmm... 
kword's okay. i don't know about abiword. ms word is really nice. whatever 
medium needs to include support for embedded images (diagrams, etc) in case 
somebody (like me) decides to break out UML for some of the design issues.

> 5 Who gets CVS write access?
>   5a function-related accounts
>   5b personal accounts

compartmentalize the server and assign a maintainer for each module. that 
person will maintain permissions for their own part of the project. this 
would include:
        - server
        - metaserver
        - common
        - each ruleset
        - each client
        - ai
        - graphics
        - sounds
        - build (somebody has to do the dirty work).

> 6 Which system for bug reporting / patch tracking will be used?
>   6a Freeciv's
>   6b sourceforge/etc

that's a good question too. bugzilla is probably more capable, but a little 
more complicated. my personal preference would be to use sf... just to keep 
everything together.

andy