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

[Kevin Brown <kevin@xxxxxxxxxxxxxx>]

Since Justin wanted some responses to his arguments about the UI and
documentation, I thought I'd give him one.  :-)

Justin Moore <justin@xxxxxxxxxxx> wrote:
> 
>    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

What's interesting about this article are the comments that follow
it.  One can easily come to the conclusion that computer users don't
want to learn anything and would much rather have someone babysit them
through the entire process of operating the computer than learn how to
do it themselves.

What I come away from that article is this: we should target the user
interface and the documentation to the actual audience.  Not the worst
performer, not the best performer, and not the developer who is
familiar with the internal workings of the program.

I think the documentation system we have is a good start, but it could
use some polishing up.  In particular, we need a description in the
help browser of all of the user interface features, including all of
the indicators (such as the knowledge progress indicator, the global
warming indicator, etc.).  Anything that has graphics associated with
it (such as terrain) should include an image from the current tileset
so that the user will know what to look for on the map or elsewhere in
the game.

The documentation should include a tutorial and a description of how
to do things like control the production in a city (for instance, how
to move citizens from one place to another to affect how much the city
produces).  If it can be done in the program, it should be documented
in the help browser.

> 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.

Take a look at TEG (Tenes Emapandas Graciela, http://teg.sourceforge.net).
It's a client-server implementation but allows you to start a server
and add bots from the main program.  We should seriously consider
doing something similar.

> 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??)

Definitely.  This might be harder than you'd think, since the server
is designed to accomodate multiple human players.  What do you do?
Only allow those who are connected from the same machine that the
server is running on save and load games?

> - The user should be able to change tilesets (although not necessarily
>    between iso and non-iso) in the middle of the game.

I agree, but submit that they should be able to change between iso and
non-iso.

In reality, I think one of the clients should be written in OpenGL.
It seems to me that you'd get a great deal of flexibility out of such
a client without having to do too much in terms of the code, but I
know next to nothing about OpenGL in general...I've just seen what can
be done with it.  The benefit is that you would automatically get
top-down or isomorphic or any view in between for free.  Do it right
and you could make the game look REALLY COOL.  People like eye candy
and I think an OpenGL client would have more potential to give it to
them than any other kind of client.  With such a client we could blow
Civ3 out of the water for eye candy...

> - 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*.

Better: they should be able to make all of these changes from the same
GUI client that they use to play the game with.  At the very least
the program that does this should be called up whenever the user
selects the "game preferences" menu option.

> - 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.

Perhaps, but if you read the thread following the advogato article
you'll see a lot of people saying that most users don't bother to
report bugs in any meaningful fashion.  But I don't know if that would
apply to the typical Freeciv player or not.

> - 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.

All of this should be done on a web page.

>    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?

But the interesting thing is that a great deal of this is the result
of the development model being used.  Change the development model to
make it much easier to get major changes into CVS and you'll see a
much faster rate of improvement.

>    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 completely agree.  I'm constantly amazed at how many people here
treat Freeciv as if it's a mission-critical application.  I suppose
that it is to some.  :-)


-- 
Kevin Brown                                           kevin@xxxxxxxxxxxxxx

    It's really hard to define what "unexpected behavior" means when you're
                       talking about Windows.