PROJECT: The readme

[Martin Gühmann]

Originally posted by E in this post
Once I finish these options I commit my latest(and after you guys point out all my mistakes) then I'll release another revivision build

So let's talk about the readme, E. What you write there cannot be understand easily. And this has to do with structure.

The first thing to note about this readme is that it is a simple text file. Therefore we have no fancy means of formating our text. The only thing we have are spaces. Tabs don't work since they may look on every editor different.

So here we have our first conclusion: Don't use tabs.

Since we can only use spaces to align text we have to take care that some word warping does not destroy our space-based formating. Our space-based formating is destroyed if the editor wraps a line, so we have to avoid it. And to avoid it we can apply to rhe line a character limit. And as we don't know what kind of screen resolution our player uses we have asume minimal conditions. And those condition for a character line limit are 80 characters. What a windows 98 DOS box displays IIRC. And you shouldn't forget that CTP2 is from our point of view a game for ancient computers.

So we are at our second conclusion: Don't use more than 80 characters per line.

Well For that we can accept some rare acceptions. And this isn't applied to the entries of the beginning where you have some 90 characters per line.

Well that were the limitions of the expected viever/editor, now we have some things about the format that is done all over the document. One thing is that each entry of playtest is seperated by one line, neither by two lines nor by zero lines.

The third conclusion is: Always seperate the entries by one line.

Then you introduced adding the revision number to the date. As you refer to it in the playtest thread this is a really good idea. But for some reason you forgot. But actually I exspect that you add it espeacilly since it was your idea.

The fourth conclusion: Add the revision number to the playtest release date.

Now let's go to the stuff you write, even simple text needs some structure and that's not only its formating but how you order the information not only in a whole text but also on the level of single sentences. So that the reader can understand it easily.

Fortunately I don't have to write this all on my own since others have already done it.

So (fifth conclusion if you want) read the text The Science of Scientific Writing.

They condense the text into seven principles which you should apply on the stuff you have written since October the 5th 2006.

Probably we have to talk afterwards a little bit about it and that may be just your first trial. But one thing is clear the readme in its current state cannot be released.

-Martin

[Martin Gühmann]

Obviously E, you got plenty of time, that allowed you to release another playtest. But why did you forgot to update the readme, since this is a prerequisite to realease another playtest.

So E, how far are you with reading The Science of Scientific Writing?

-Martin

[Ekmek]

reading is whats slowing me down i kicked out the build so i can start on the readme

[Ekmek]

i did my best cleanup and added Revision numbers back to May 2005 (the beginning of our current Revision report Thread)

[Martin Gühmann]

Originally posted by E
i did my best cleanup and added Revision numbers back to May 2005 (the beginning of our current Revision report Thread)

Well actually I didn't thought of adding revision numbers before you introduced them, but it isn't such a bad idea, either.

The first thing I see is that you indeed made progress, that's good. But there is still some room for improvement. Therefore let's go to round #2.

Let's start with the layout again. You remember the time/temperature table. It demonstrats that information is easier perceived if the presentation of the information fullfills the expection of the reader.

One way to raise such expectations is to present the infomation always in the same way. Therefore we have the those tags: Added, Fixed and Changed. You notice that those words have different length. If you now continue after that keyword the text it may start in a different column dipending on the keyword you use. And this does not raise expectations. And thus makes reading the text harder. If you look carefully then you will see that I added some spaces after those keywords to align same all into the same column.

So first conclusion is to add some spaces after the keywords Added, Fixed and Changed so that the message starts always in the same column.

So for now let's move on to the text content. You have now seperated the new database flags for modders from the rest of the changes. That's nice. But now we have to figure out what is the topic and what is the stuff you want to emphasize.

The first sentence introduces that something of databases and flags is going to come. First we have a enumeration of the databases and the new flags. And for each flag we have a short description. Little sentences, well not full sentences, because the subject is missing. And that's not good, since this violates the reader's expectations. Let's see what is the subject or what should be the subject here:

Added: New database flags for modders:
- TerrainImprovementDB
ProducesEnergy - creates an energy point (supply)
EnergyHunger - subtracts an energy point (demand)

So in that case ProducesEnergy creates an energy point. Actually I prefer to put into the description as subject TerrainImprovement since we are talking about TerrainImprovements. And therefore that's the topic. So my first revision is:

Added:    New database flags for modders:
- TerrainImprovementDB
   ProducesEnergy            TerrainImprovement creates an energy point (supply)
   EnergyHunger               TerrainImprovement subtracts an energy point (demand)
- BuildingDB
   ProducesEnergy            Building creates an energy point (supply)
   EnergyHunger               Building subtracts an energy point (demand)
   EnergyHungerPerPop    Building creates an energy point (supply) per person in city
   ProducesEnergyPerPop Building subtracts an energy point (demand) per person in city
- WonderDB
   ProducesEnergy            Wonder creates an energy point (supply)
   EnergyHunger               Wonder subtracts an energy point (demand)
   EnergyHungerPerPop    Wonder creates an energy point (supply) per person in city
   ProducesEnergyPerPop Wonder subtracts an energy point (demand) per person in city
- UnitDB
   ProducesEnergy             Unit creates an energy point (supply)
   EnergyHunger                Unit subtracts an energy point (demand)

Well you may find another topic, but that's how you find it in earlier entries, and to raise expectations we should keep the format. So let's go on. You could also be more specific, creating energy is not as specific as generating energy. Even if it means the same here but a generator is something else than a creator. The other word you use "subtract" is very abstract, better use something concrete like use or consume. And what is an energy point, this is also very abstarct, if you talk you rather refer to energy which is still an abstract concept, but people are more familiar with it. And probably your nergy flags generate some certain amount of energy which is given by the flag and not just one nergy point. So here is my second revision:

Added:    New database flags for modders:
- TerrainImprovementDB
   ProducesEnergy            TerrainImprovement generates energy
   EnergyHunger               TerrainImprovement consumes energy
- BuildingDB
   ProducesEnergy            Building generates energy
   EnergyHunger               Building consumes energy
   ProducesEnergyPerPop Building generates energy per citizen
   EnergyHungerPerPop    Building generates energy per citizen
- WonderDB
   ProducesEnergy            Wonder generates energy
   EnergyHunger               Wonder consumes energy
   ProducesEnergyPerPop Wonder generates energy per citizen
   EnergyHungerPerPop    Wonder generates energy per citizen
- UnitDB
   ProducesEnergy             Unit generates energy
   EnergyHunger                Unit consumes energy

This way the whole thing looks much simpler and therefore is easier to understand. Maybe I am now a little bit inacurate by saying citizen instead of city inhabitant or by just using pop instead of it, but that's now up to the modder to figure it out. And the other nice side effect is that you don't have to add this stuff in parentfeses. Since it is now clear what is supply and demand.

ANd here you see another rule: Keep it as simple as possible.

And to remind you the structure of all these sentences is now first the topic that is in our case a member of one of these databases then we have a verb with a strong content and something we want to emphasize in the emphasize position.

One thing you note about the new flags is that they are related to rhe new concept of energy which you introduced right before as you should do. One thing you could do is to link all those energy related stuff more closely.

At first you have to introduce the concept. With what do you start, with a concept everyone is familiar at least I expect. So you can start with a new concept and then you tell what it is about namely it is about energy demand and supply.

So here is my suggestion for that:

Added:    New concept of energy supply and demand. It calculates a ratio modifier for gold and production.

Note that I broke it into two smaller units. However I still have no idea what the second part means. Anyway let's go on with the new user profile option your sentence suggests that the new userprofile option is optional which does not make much sense. You rather mean that there is a new userprofile option that makes the energy supply stuff optional.

And you could also simplify it if it is an option you have the means to disable it. So let's see what we have:

Added:    New userprofile option to disable the new energy supply demand concept.

Let's put it together with the new database flags and make the connection clear:

Added:    New concept of energy supply and demand. It calculates a ratio modifier for gold and production.
Added:    New userprofile option to disable the new energy supply/demand concept.
Added:    New database flags for modders to enable the new energy supply/demand concept:

Probably there is more stuff, but we should break it into small pieces, so that it isn't to much work at once. And of course you should go through the whole part you have improved so far to make more improvement.

Two final notes about this forum: This forum eats spaces so you have to put them on your own into the readme and this formum does not allow me to chek me the characters per line easily like you can do it in EditPlus2.

Edit: Seems like the formum does not eat spaces if you put the stuff into code blocks, but the only drawback is that the columns aren't aligned.

-Martin

[Martin Gühmann]

Well E, looks like you got some time, so where is your second revision of the readme? Come on I didn't gave you to much work, espeacilly since there is still something I haven't pointed out.

-Martin

[Ekmek]

I haven't put it up yet because I got bogged down in trying to fix a bug that I PM'ed you about.

[Ekmek]

Here's the readme in prep for for my 719 revision if i figure out whats wrong with the SectarianHappiness code

[Martin Gühmann]

Let's see, from a first glance it looks better. So far so good, but there is still room for improvement.

Well I should start with the earlier texts: Those for Revision 687 and Revision 692.

Implemented HasAirport Icon.

Here I wonder what this HasAirport icon is used for. Where can I find it.

Player Capitols now have a star Icon.

A star icon, maybe I see it when I open the city manager. Again where can I see it? By the way Capitals is enough, we are playing civilisation and we know that each civilisation has a capital. A capital is by the way something else than a capitol. In CTP2 is just a building that turns a city into a capital and in a city of the real world it may be a capital building, too. Well originally a or the Capitol was just a hill in Rome.

Let's go on:

The rest of Revision 687 seems to be okay, except that those lines are longer than the 80 characters.

Civilization Flags for Units

What kind of civilisation flags, can I see them in the build manager?

Moved Goal text from appearing inside the science box in the english/science.ldl

What is english/science.ldl? You should keep in mind that an average player has no idea what this is about. But anyway you could start the line with: "English version only" Then it is clear what you mean.

Anyway in addition the lines for Revision 692 are too long.

Anyway you should go to all the other revisions as well and check whether you can revise them, for instance if they are to long, whether you can shorten them. If they are short whether you can add some bits of information to make them clearer.

Check also whether there are too many free lines. Yes, there are but you have to find them on your own. And there are still some tabs in.

Check also if you have still some database flags in the main body of the messages instead in their extra database section for moders. And yes there are some, but again that is your task to find them.

Now let's go to another problem, it looks like that you just add your own stuff and let the playtester to figure out what else has been improved.

Namely I modified the strategies.txt so that the AI uses better governments earlier in the game. I also fixed something concerning AI transport usage and a trun lack. There was also something about progress bars. And some more stuff, so go through the revision report and add all the relevant stuff.

So what is relevant stuff?
Everything that changes the game for the player or for a modder.

What are changes for a gamer?
Everthing that modifies the game in a visible way or in a more subtile way like the AI.

What are changes for a modder?
Everthing that enhances the modding cabability.

What enhances the modding cababilities.
Adding new database flags or adding new databases or adding new slic function and maybe something I forgot.

And what is not part of that?
Everthing that does not change the game in any way for gamers and modders. For instance all those code standardisation stuff Fromafar does or your future use stuff. If you add it but it does nothing then nothing changes for players and modders.

So go through the readme make the changes, repeat this once or twice and post again.

-Martin

[Ekmek]

Originally posted by Martin Gühmann
Now let's go to another problem, it looks like that you just add your own stuff and let the playtester to figure out what else has been improved.

I thought each coder was responsible for inputting their changes into the readme?

[Martin Gühmann]

Originally posted by E
I thought each coder was responsible for inputting their changes into the readme?

No, the guy who releases the playtests is responsible for the readme. The readme was always made and corrected at the last minute. With the last playtest I released I also updated the readme to include everthing that has been done and also the latest changes. And what logic is there behind to release a playtest without a complete readme?

Well, since you are currently releasing playtests it is your task to polish it so that the playtester gets all the necessary pieces of information.

-Martin

[Ekmek]

[Martin Gühmann]

Well, that's also one reason for this thread. And actually it teaches you also some nice kills about how to write a text so that people who are slow at reading can read it faster.

-Martin

[Martin Gühmann]

Well E, looks like you got some time again, so where is your third revision?

-Martin

[Martin Gühmann]

Well E, as it seems that you have some difficulties to do your work I thought you need some help, therefore I put some nice comments into the readme, extra for you.

This should now make it very easy for you to eleminate all those tabs and longliners.

-Martin