[Freeciv-Dev] Documentation, Usability and Development

[Justin Moore <justin@xxxxxxxxxxx>]

   After reading over some of the comments on Slashdot and the posts to
this list that followed, I'd like to throw in a few of my own thoughts.
First off, I'd like to point people towards this article:

http://www.advogato.org/article/374.html

It talks about what the average user wants in terms of documentation, but
also drifts into usability.  Freeciv may have a pretty good game engine
under the hood and be pretty flexible, but quite frankly the UI leaves a
lot to be desired.  And I'm not just talking about the dialog boxes or
which mouse buttons do what.  I'm talking about just getting the game up
and running.

   Before I rant and rave too long, let me say that I realize most Freeciv
users are probably going to be more technically competent than the average
gamer.  But that's still no excuse for a poor UI.  Another disclaimer is
that I do plan to work on some of these points, but not until my winter
break (mid-Dec); I don't want to come off as just whining about things I
have no intention of trying to fix.

   Having said that, here are my current list of grievances (everyone warm
up their flamethrowers now :)):

   When a first-time user downloads freeciv and wants to start playing,
odds are the first game is going to be them against a few AI.  They don't
want to bother with starting up the server, starting up the client, trying
to figure out what server variables do what, start the game, have it crap
out because the path doesn't have the rulesets in it, re-set the path,
etc, etc, etc.  They want to:

- Click "Freeciv" in their window manager menu
- Have a GUI pop up that lets them start a new game, load a game, connect
    to an existing game, etc
- Click on "new game"
- Quickly and easily find the "Pit me against 2 AI"
- Select a nation
- Start

Or, alternately,

- Do steps 1 & 2
- Click on "load game"
- Load the appropriate game
- Start

Or,

- Do steps 1 & 2
- Click on "connect to an existing game"
- Select the host/port
- Start

   We need a GUI that pops up when the user just types freeciv or clicks
on the menu.  For the average user, two processes are a hassle.  This
first-stage GUI can exec the civserver and civclient with the appropriate
command-line options, but the user doesn't need to know the details.
More importantly, it can check up front to make sure various parameters
are set *before* these two processes start up, rather than give some error
message about incorrect path, etc, etc.  We've got error-checking and
other such routines in common/, let's use them.

- This GUI must have a universal config file, such as $HOME/.freecivrc
- $HOME must be the only environment variable the user has to worry about.
    Everything else should be in the config file ($FREECIV_PATH must die).
- Make the common case fast: figure out what most first-time users want,
    and make it such that a brain-dead, on-a-feeding-tube parrot can use it.

Other notes:
- The user must be able to save the current game and load or start another
    game mid-play (how did we make it to 1.0 without this feature??)
- The user should be able to change tilesets (although not necessarily
   between iso and non-iso) in the middle of the game.
- The user who is controlling the server should have a nice GUI they can
    use to change all the values.  I saw a few different attempts to make
    some sort of GUI (Tcl/TK, gtk) but *none that are in the main
    distribution*.
- We need to liberally sprinkle the GUI with places to contact developers
    with comments, and encourage them to do so early and often.  We need
    bugzilla which, contrary to what some people may say, doesn't take a
    lot of big iron to run.  I have it up and running on a 486 with an old
    IDE drive.
- It would be very nice for the bug reporting tool to be able to download
    a quick summary of the state of our bugzilla.  How many bugs, average
    initial response time, etc, etc, and make that readily accessible to
    the end user.  If they see in "real time" people working on Freeciv,
    they may be more likely to send something in because it would feel
    less alien or less abstract to do so.

   I think a lot of the developers here spend too much time discussing the
finer points of the implementation and not enough time looking at the Big
Picture.  Users most likely don't care if changing foo() from a function
to a macro gets them a 5% speedup in the AI if they can't even get the
damn thing up and running.  I've noticed a trend to lay out all these
grand plans or visions, but oftentimes not much to follow up on that.  And
even the simple stuff ... for chrissakes, how long do borders or sound
patches need to float around before they finally make it into the tree?

   And you know what?  If the first version of the GUI is gtk only and
only works on linux, portability be damned.  If it's stable, put it in
CVS.  Get it out to the masses.  Eventually one of us (or someone else)
will write the Xaw or windows or whatever client if they really want it.
Isn't that what open source is about?  Responding to user needs faster
than the other guys?  Being more innovative and ahead of the curve?  Who
gives a damn if the first version of this is limited?  It's the *CVS*
version of a friggin *open source game*, not the final release of a major
OS or application.

   I know I've mentioned this in the past, but we desperately need a
testing or development branch in CVS.  Depending on people's comments on
these ideas, we could potentially have a healthy chunk of new, almost
completely-unwritten code for new coders to delve into.  Again, we need to
make the path into the development community an easier one.  Rather than
say, "Well there's this chunk of code, bar.c, that the rest of us are
afraid to touch, why don't you have a go at it?" we need to say, "We need
a new whiz-bang GUI that is mostly independent of the current codebase,
have at it."

   With the development branch, we need to get the code into CVS so a)
more people can look at it and fiddle with it, and b) the new developer
feels like they're actually doing something productive.  I've sent in at
least a dozen patches which have all been dropped or rejected for some
reason or another.  I'm still here (for better or worse)  because I'm
stubborn and I really want to help.  I may try to revive some of the
patches or work on other stuff during break, who knows.

   Remember, we're making a game here, not an essential application.  If
people (or developers) don't particularly like it off the bat, they're
going to move on.  We've got a great game engine and tons of good ideas
and good programmers.  Let's try to capitalize on that.

Ok, so that turned into a longer rant than I had originally planned.
Maybe someone should confiscate my soapbox before I do any more harm. :)

-jdm

Department of Computer Science, Duke University, Durham, NC 27708-0129
Email:  justin@xxxxxxxxxxx