Documentation: Manuals and Tutorials

[Mark_Everson]

Hi Blakis Maximus:

Good to see you're intrigued Thanks for the encouraging words! How did you come upon Clash anyway?

If you email me at markeverson@mediaone.net I will mail you the source. It won't be runnable since there will be changes in a couple of days that will mean we'll no longer require the Xerces xml package to run. So I'd prefer for now just to send you the source and a couple of the xml ini files for you to look over. That way you won't need to get xerces etc. You can then look over where things are and whatever. If you absolutely want something runnable, I suggest you wait a few days.

The Clash equivalent of a city is a province, which is a city plus the other land. We clearly need an overall Province GUI at some point... There is no such view because we haven't gotten 'round to it yet. The econ screens do some of that stuff, as you probably know.

Probably the best up-to-date thing to look at is the D6 manual. Therein you can find the meaning of the power word ROI!

Looking forward to more fresh-eyes comments, and even More to putting you to work at some point in the future.

-Mark

[Blakis Maximus]

Hi Mark,

I sent you an email - thanks by the way. I peruse the threads here at Apolyton and Civilization Fanatics, mainly in the Customization and Creation sections since I feel Civ III is lacking in some important ways. I saw your response in one of the threads here with the link in your sig. Since then, I've been trying to read as much as I can about the project. I like what I see!

On a different note, have you implemented your own XML parser or are you scrapping XML and moving to something else?

Blakis

[Gary Thomas]

On a different note, have you implemented your own XML parser or are you scrapping XML and moving to something else?

We have our own XML parser which uses reflection in order to be very easy to use. We don't need the features of SAX or the general horrors of DOM. Zipped, our parser code is 8K...

Cheers

[Mark_Everson]

Originally posted by Blakis Maximus
I saw your response in one of the threads here with the link in your sig. Since then, I've been trying to read as much as I can about the project. I like what I see!

Good to see all the not-so-subtle plugging is paying off!

Blakis, could you copy your initial post over to the D6 thread? That way, the next time I sweep through it to update the bug and small feature lists, it will be there so I won't forget. If you can also tack on Gary's responses from this thread it'd be great. (In case you don't know how... Just edit his post so you can copy the whole thing including codes, and then tack it on to the end of your new post with something like "Gary Thomas' Responses:".)

[Blakis Maximus]

It's now posted in the Demo 6 Comments and Bug Reports thread...

[Mark_Everson]

Time to start thinking about this again as Demo 7 approaches. Chris W. was never able to do anything on the manual. We have a new guy who is going to give it a shot, who hopefully will be introducing himself soon. Please make any further comments on the manual here if you want your ideas included in the rewrite for D7.

Here are my high-level thoughts on the issue to get the discussion going again:

I think the best thing to do is that we aim for all of: a manual, tutorials, something like a civilopedia in civ, and an online tutorial. So if you can try and write the manual in small enough pieces it can be used in any of these, I think that's best. That said the questions that most come up in the D6 thread are obvious places to improve the manual.

See also: The On-line help system

Reworking our Demo Approach

and starting with Gary's post of 29-03-2002 17:07 in the
Planning for Demos 7 & 8 thread.

[axi]

Mark: I don't have much to say about the manual. I feel it should begin as a walkthrough and then have chapters explaining the various models. In-game help is out of my league.

[Erasmo_Ramos]

Hi everyone,

I'am the new guy who is going to give a shot at writing the manual. My main goal at writing this manual is to make it understandable and cover enough material so people playing won't get lost.

Right now I'am deciding on what the layout of the manual is going to be. My idea is simple:

1. Sections that give info on certain areas of the game.
2. At the end of each section give a small tutorial on how to use what the section talked about (I.E. How to move a unit)

I will also try to make a tutorial for those ppl that don't want to read.

[Mark_Everson]

Hi Erasmo, and Thanks for putting effort into this important area.

Axi's idea of starting with a walkthrough for each area seems good to me. The walkthrough parts could serve as a component of the online tutorials nicely also.

Looking forward to seeing what you come up with!

-Mark

[Mark_Everson]

how to handle messages in tutorial

I am beginning to work on the in-game tutorial for Dawn1 in Demo 7. (Erasmo has pulled out due to lack of time, leaving me as the sucker-by-default...) This will use Gary's Event system to display messages to the player when appropriate.

My immediate question for now is what is the best format to use for these messages. I need to know what I can use for D7, and also would like to have an idea of where we're headed longer-term.

1. Can they be HTML, or must they be plain text for now? Long-term I think we've agreed they should be HTML.

2. Must all messages be in individual files, or can we use a tagging system to put them all in an xml file? The former would work for now, but I think may quickly get out of hand. The latter is my long-term preference, but not based on a huge amount of thought.

[LDiCesare]

You can use message files with tags like <message id="">
Whatever is inside the message tags is shown to the player. The id allows to find the correct message in the file. Actually, it is a goos idea to load the file once and build a hashmpa of messages if you do it that way.

[Mark_Everson]

Thanks Laurent, that's good to know. I'll assume that's the way it'll be handled for now, pending hearing from Gary. I hope to have some examples soon that I can post and ask people if they're heading in the right direction for what we need for D7.

[Mark_Everson]

I just tried setting up my first tooltips for the old econ gui. In some cases I'd like them to be several lines long, for example to explain ROI's uses. When I put in a long text (several hundred characters) only a small part of the tooltip message ended up getting shown. Anyone know if there's an easy way to override this behavior so you could have a looong tooltip? I guess I'd need to override one of the ToolTip methods in JComponent or something like that. Anyone know offhand what the right way to do it is, since I need to get back to work anyway , and this is not urgent.

[LDiCesare]

I don't know much about tooltips, but I think long tooltips are bad from an ergonomy point of view.
Based on comments by Age Of Wonders designer, tooltips are slow to show and not very efficient for that reason: You put your mouse somewhere, then wait for the tip to appear. They used a text pane in the lower part of the screen to show tooltips instead of popping them up in that game. That means you would have a permanent text zone (in that game, it was one line but it spred the whole screen wodth) in which tips appear. We could use that, maybe make it 2 lines long if you really need long messages. Also, with such a text zone, you could have a Help/Details button or whatever which would launch the online help on the appropriate topic.
That would let you use one or two screen-width of characters, probably around 100-200 characters, plus maybe a scrollbar?

[Mark_Everson]

Hi Laurent, yeah I think you've got a point. Well, I'm using tooltips for now since they're easy. But tooltip-like comments could go in a dedicated area like you say. I thought the text box of maybe 6 rows at the bottom of the screen in EU2 was useful. Have to talk this one through, but so far your idea sounds good.