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

[Justin Moore <justin@xxxxxxxxxxx>]

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

   Thank you, Kevin. :)

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

   Actually I think we should target it just below what we think our
actual audience will be.  At the very least someone who's never seen
Freeciv (or even Civ) before should be able to *start* a game.  We may not
need to follow all of the little "have a screenshot every 3 steps" rules,
but we need to always remember that we're going to take things for granted
that a new user won't.

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

   Amen. :)

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

   Sourceforge is a bit slow right now (amusingly enough my junkbuster
gives me a "connection failed" attempt when trying to load the
teg_connect.jpg graphic :)).

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

   Tenatively I'd say that whoever has ALLOW_HACK permissions should be
allowed to save and load games.  They have access rights to pretty much
everything else.  If you can force the game to end, you should be able to
force the game to "end" by saving and loading a new game (or loading a new
game).

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

   Well, yes, I was thinking smaller steps, though.  I'm not sure what
kind of magic the client contains to do iso and non-iso tilesets.  Perhaps
someone else can comment on that?  Jason?  Thue?  Raimar?

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

   I agree.  The difficulty comes in making 3D images for the different
units and the terrain.  A lot of the stuff in the plain client/ directory
may not apply since the whole tileset mechanism would kinda go out the
window.  Again, I don't know what this would or wouldn't take to complete.
Comments?

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

   Well, that's what I meant. :) The unifying GUI would tied to stdin and
stdout on the server, and could set all the variables that way.

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

   We probably get more bug reports than the average application the
article was referring to.  Plus we could do things like have an option in
the GUI to ask the user if they want to be prompted to send in a bug
report if freeciv crashes or something goes wrong.  If we integrate the
feedback form into the game, it'll seem less alien to send it in.  The
feedback form could simply do a POST operation to a HTML form somewhere on
the website.  That way they don't have to quit freeciv, log into their
e-mail, yadda yadda yadda.  They just have to be online.

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

   All of this should be on the web server.  The actual form I was
thinking of was a chunk of code in the client to download, parse, and
present this information to the user from within freeciv.  This should,
again, make the bug reporting less alien and more familiar.

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

   Exactly.  But somehow I get the impression that we're preaching to the
converted (the two of us :)).

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

   If "mission-critical" can be defined as "something I sneak off and work
on my when my advisor isn't looking", then, yes, it's a MC app. :)

-jdm

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