Ufo2000 Documentation Refreshment - All Members Please Read

[Blood Angel]

As you may or may not be aware I have taken it upon myself, at Nachtwolf's suggestion, to lead up the documentation review for UFO2000.

 

Right, first things first, the documentation in the current release (0.7.1062) constitutes the following:

 

readme_de.txt - Manual in German

readme_en.txt - Manual in English

readme_es.txt - Manual in Spanish

readme_fr.txt - Manual in French

readme_pt.txt - Manual in Portuguese

readme_ru.html - Manual in Russian (presumably in html to handle cyrillic?)

AUTHORS - List of contributors to project, somewhat out of date

Changelog - Doesn't look like it's been touched since 0.6.627

COPYING - Seems to be just the wording of the GNU licence

INSTALL - Installation notes

 

The last four files do not appear to have the .txt format ending, but open nicely in notepad. Vets/those who know what they're talking about, could you tell me if there is a specific reason for this, or could we put those files into .txt or even .html?

 

Now, to business, firstly the existing manuals. I've perused the English version and it seems fairly up-to-date, however, not exactly future proof. There's certainly room for improvement. If anybody would like to verify that the alternate languages are as correct as the English translation I would very much appreciate this.

 

The AUTHORS file needs an update. I would like anybody who has any information about their or other people's contributions to the project so far to either post in this thread, drop me a PM, or email me, in that order of preference. That way we can make sure that no contribution goes unheeded, which is a somewhat unpleasant state of affairs that nobody wishes, I'm sure.

 

Thirdly, the changelog. Basically, if any dev has had the presence of mind to keep a changelog or willingness of inclination to dig one up for everything that has happened since the last update to the changelog (December of 2004 - urk), it would be useful. Alternatively, we could pick up where we left off, or just scrap what exists and start afresh.

 

Onwards to the installation instructions. I'm going to be somewhat radical here and suggest a rather extensive re-write. Basically, I propose that we have two seperate guides - a basic guide for your average newbie, who isn't too hot at this whole deal, and would like to have their hand held until they can get in game; secondly a more advanced guide for those 1337 chaps who desire to compile their own versions, and would appreciate some guidelines tailored for his needs. Any thoughts on this?

 

Now that the existing documentation has been discussed, perhaps some ideas for more documentation that could be included? Any ideas are welcome. I'm thinking that some, if not all, of the information on the UFOpaedia could be inscribed to this end.

 

 

That's all from me at the moment, input would be appreciated.

[playstationman]

The last four files do not appear to have the .txt format ending, but open nicely in notepad. Vets/those who know what they're talking about, could you tell me if there is a specific reason for this, or could we put those files into .txt or even .html?

Tradition, mostly. Almost all programs made for UNIX-likes contain said files, without the txt ending. (on UNIX-likes, a file without any extension is generally assumed to be either a program or a plaintext file)

 

Basically, I propose that we have two seperate guides - a basic guide for your average newbie, who isn't too hot at this whole deal, and would like to have their hand held until they can get in game; secondly a more advanced guide for those 1337 chaps who desire to compile their own versions, and would appreciate some guidelines tailored for his needs. Any thoughts on this?

Your average newbie probably shouldn't be compiling from source in the first place - they should be installing through their package manager, or just using the installer for those under MS Windows.

[Patrick1994]

cool

i didnt think the documenation in the most recent beta wasnt that good

[Blood Angel]

The last four files do not appear to have the .txt format ending, but open nicely in notepad. Vets/those who know what they're talking about, could you tell me if there is a specific reason for this, or could we put those files into .txt or even .html?

Tradition, mostly. Almost all programs made for UNIX-likes contain said files, without the txt ending. (on UNIX-likes, a file without any extension is generally assumed to be either a program or a plaintext file)

 

So there's a reasonably strong argument for putting them with the .txt? Just to make life easier for us of us running Windows?

 

Basically, I propose that we have two seperate guides - a basic guide for your average newbie, who isn't too hot at this whole deal, and would like to have their hand held until they can get in game; secondly a more advanced guide for those 1337 chaps who desire to compile their own versions, and would appreciate some guidelines tailored for his needs. Any thoughts on this?

Your average newbie probably shouldn't be compiling from source in the first place - they should be installing through their package manager, or just using the installer for those under MS Windows.

 

That's my exact point - The average newbie who will be installing from packaging and needs his hand held for installing other things (maps, weaponsets, skins etc) will need a different guide than people who are prepared to compile for themselves, and might need more advanced knowledge and a guide tailored towards just pointing them in the right direction.

Edited February 16, 2007 by Blood Angel

[Oldtype]

So there's a reasonably strong argument for putting them with the .txt? Just to make life easier for us of us running Windows?

I wonder if it would actually make life easier. They may look good in wordpad, but they should look bad in notepad. That is because UNIX text format is slightly different than windos text format. This is about line endings mostly.

Anyway why would normal windows people even want to look at those files?

That said, most text editors used in unix can read the windows format too, so I guess you could convert them to windows format and put a .txt ending. That would not be traditional though and it could cause problems with those few editors that do not support windows format.

Either way I do not realy care.

[Oldtype]

If anybody would like to verify that the alternate languages are as correct as the English translation I would very much appreciate this.

Once someone has confirmed that the english file is up to date, I can make sure the german file is in sync.

The AUTHORS file needs an update. I would like anybody who has any information about their or other people's contributions to the project so far to either post in this thread, drop me a PM, or email me, in that order of preference. That way we can make sure that no contribution goes unheeded, which is a somewhat unpleasant state of affairs that nobody wishes, I'm sure.

svn should keep track of who commits stuff.

Thirdly, the changelog. Basically, if any dev has had the presence of mind to keep a changelog or willingness of inclination to dig one up for everything that has happened since the last update to the changelog (December of 2004 - urk), it would be useful. Alternatively, we could pick up where we left off, or just scrap what exists and start afresh.

on commit the devs should have submitted comments with each commit, those comments would make up a changelog. So again look into svn.

Onwards to the installation instructions. I'm going to be somewhat radical here and suggest a rather extensive re-write. Basically, I propose that we have two seperate guides - a basic guide for your average newbie, who isn't too hot at this whole deal, and would like to have their hand held until they can get in game; secondly a more advanced guide for those 1337 chaps who desire to compile their own versions, and would appreciate some guidelines tailored for his needs. Any thoughts on this?

mmhh readme should be something like the basic thing you want. The INSTALL file would be for those crazy people. Is there need for more?

I'm thinking that some, if not all, of the information on the UFOpaedia could be inscribed to this end.

I do not think that is such a good idea, because that info would have to be updated too. A link to the wiki would be better I think.

[Serge]

As you may or may not be aware I have taken it upon myself, at Nachtwolf's suggestion, to lead up the documentation review for UFO2000.

 

Right, first things first, the documentation in the current release (0.7.1062) constitutes the following:

 

readme_de.txt - Manual in German

readme_en.txt - Manual in English

readme_es.txt - Manual in Spanish

readme_fr.txt - Manual in French

readme_pt.txt - Manual in Portuguese

readme_ru.html - Manual in Russian (presumably in html to handle cyrillic?)

AUTHORS - List of contributors to project, somewhat out of date

Changelog - Doesn't look like it's been touched since 0.6.627

COPYING - Seems to be just the wording of the GNU licence

INSTALL - Installation notes

 

The last four files do not appear to have the .txt format ending, but open nicely in notepad. Vets/those who know what they're talking about, could you tell me if there is a specific reason for this, or could we put those files into .txt or even .html?

I guess these uppercase file names for INSTALL, COPYING, AUTHORS, etc. may be derived from GNU Coding Standards. We don't strictly follow these standards anyway

 

Now, to business, firstly the existing manuals. I've perused the English version and it seems fairly up-to-date, however, not exactly future proof. There's certainly room for improvement. If anybody would like to verify that the alternate languages are as correct as the English translation I would very much appreciate this.

I remember there was a html manual with some introductory information and screenshots floating around somewhere. Nicely formatted html with pictures is more user friendly. Also it is possible to publish it on the webpage.

 

You mentioned russian manual, it is a bit different from the others as it is much more detailed and is written in a kind of comprehensive and entertaining style (some people seem to be really good at writing texts).

 

But actually I got somewhat discouraged with the idea of having readme files for many languages (hard to keep all the translations in sync). So now I prefer making lots of hints and help messages all over the places in the game itself. And there are tools (gettext) which help to keep translations of game messages in sync.

 

Thirdly, the changelog. Basically, if any dev has had the presence of mind to keep a changelog or willingness of inclination to dig one up for everything that has happened since the last update to the changelog (December of 2004 - urk), it would be useful. Alternatively, we could pick up where we left off, or just scrap what exists and start afresh.

A detailed SVN changelog is here:

http://ufo2000.svn.sourceforge.net/viewvc/.../trunk?view=log

 

You can also find information about all the contrubutors there. If the person who committed code to the repository is not the author, actual contributor is mentioned in brackets.

 

A summary of the most important changes can be found at: http://ufo2000.sourceforge.net

 

Onwards to the installation instructions. I'm going to be somewhat radical here and suggest a rather extensive re-write. Basically, I propose that we have two seperate guides - a basic guide for your average newbie, who isn't too hot at this whole deal, and would like to have their hand held until they can get in game; secondly a more advanced guide for those 1337 chaps who desire to compile their own versions, and would appreciate some guidelines tailored for his needs. Any thoughts on this?

Installation instructions are generally available for alternative platforms such as linux, mac os, etc.

Newbee windows users don't need any installation guide, they just need to start the installer and follow the instructions.

 

Installing extra expansion packs (new maps and weapons) is a different matter though

[Serge]

Wow, there were lots of messages added since I had last refreshed this thread in my browser. Only just noticed that after posting a reply

[Pi Masta]

FYI the .txt extension is nice for windows people, though if it has pure Unix line ending it will look like crap in notepad. Fortunately wordpad will format it correctly. Main argument I have is that on windows you can't associate a file with no extension. I'm sure *nix can associate it, if it already hasn't.

 

Converting between these two formats is simple, and very common. The C standard library even makes a distinction when reading files in binary or text mode. Even FTP protocols have the ability to switch from Binary to Text modes when transferring (normally done transparently)

 

To be specific *nix ends their lines with line feed (character 10), while windows does linefeed followed by carriage return (character 10 followed by 13), converting between the two has been around forever. (I believe Macs end with just character 13, though probably changed to *nix's 10 with OS X)

[nachtwolf]

As you may or may not be aware I have taken it upon myself, at Nachtwolf's suggestion, to lead up the documentation review for UFO2000.

 

That's great news! Thanks a bunch buddy!

 

Everybody, praise Blood Angel for doing the paperwork.

 

 

Enough now.

 

BTW I love your signature pic with the little busy monk.

 

Ok now with the serious stuff :

 

The last four files do not appear to have the .txt format ending, but open nicely in notepad. Vets/those who know what they're talking about, could you tell me if there is a specific reason for this, or could we put those files into .txt or even .html?

As long as it doesn't break anything, add the txt. But having a copy could be more interesting maybe. Serge, any thoughts? You were a bit blurry on that one.

 

If anybody would like to verify that the alternate languages are as correct as the English translation I would very much appreciate this.

I asked JFarceur a bit earlier, him and I are willing to split the work on the French documents.

 

---

 

For the LOG files, I can send you a copy if you don't have access to SVN's log.

 

As for HOW TO INSTALL/ PLAY, I have no decent relevant experience in Linux/Unix, but I can tell you need to tell people how to install from a windows installer.

[Blood Angel]

Wow, that's a whole lot of responses.

 

Nacht, thankyou for your appreciation.

 

Firstly, to the .txt saga. The aim of the project is, as with most similar projects, to make it easy to use for everybody. Normally the way this is achieved is by putting hard work in at our end. I'm no expert, but I'm fairly sure there should be a format that will work for everybody. So far we have:

 

Blank file format. Can be read with ease on *nix, and can be manhandled into working on Windows.

 

.txt file format. Easy for Win, perhaps problems for working in *nix, but maybe not.

 

I think there are two major things we should consider for this: Firstly, the fact that Windows refuses to associate blank file formats, for some reason known only to Nurgle himself. Secondly, there are, to my knowledge, a great deal more players on Windows systems than there are on *nix. However, as people have noted, the kind of player with the patience and knowledge required to run a *nix box is more likely to be reading these files than Windows newbies. I suggest that for the time being we should leave the files as they are, and deliberate on the matter when we've made some more urgently-needed changes.

 

Righto, next issue. I say fair play to those who pointed out that the INSTALL file is for the hardcore nutters for whom packaging systems are passé and the only *real* way to install is with a magnetized needle and a steady hand. The more and more I think about it, they're right. Serge raised the issue of guides for installing extra content, and I think he's hit on something here. We should explore this idea at some point.

 

Nachtwolf, I would be delighted if you could send me an SVN log as I really don't have much of a clue of how SVN works, or even what it's for.

 

Now, something of a shakeup. I've been thinking, and I have a radical proposal.

 

Basically, I propose that we replace the six different translations of the readme and the Russian manual, with a new, scratch-built English manual, probably in HTML, which should be the first port of call for any new player. For this we will need several things:

 

Firstly, I would very much appreciate if anybody could translate the existing Russian manual, which Serge assures me is superior to the readme files. This additional information in comparison to the readme files, could prove to be a very useful resource in future writings.

 

Secondly, it would be useful if we could establish a firm base. We are at a stage in the development where a great number of visual changes are taking place. For instance, I have heard rumblings of Nachtwolf designing the if-you-see-Kay out of a new mission planner interface. If we were to write a manual for one interface, only to have to rewrite it for a new one, to quote SEGA, "that's no good".

 

Thirdly, I need your input, so please respond to my points

[Serge]

The last four files do not appear to have the .txt format ending, but open nicely in notepad. Vets/those who know what they're talking about, could you tell me if there is a specific reason for this, or could we put those files into .txt or even .html?

As long as it doesn't break anything, add the txt. But having a copy could be more interesting maybe. Serge, any thoughts? You were a bit blurry on that one.

Well, the point is that I don't care much, we can keep existing files or change their names to something new (anyone can feel free to propose a new layout). Anyway, these files are only accessible for 'power users' who can find ufo2000 folder in windows program files. Right now only readme files shortcuts are added to start menu. It would be probably best to add all the important information to these readme files and to the game itself if we want the casual users to find it. For example, many games have information about the authors and contributors accessible from menu ('credits' or 'about' button) or shown in the final victory screen (fo single player games). I'm not suggesting to do this immediately for our next release, we may split documentation improvements into several iterations and do the most important work now and the rest of it a bit later.

 

Dos/unix line endings are not a problem for us as SVN handles this issue using svn:eol-style property automagically (text files distributed with win32 installer have dos line endings, files that come in the source package have unix line endings).

[Serge]

Basically, I propose that we replace the six different translations of the readme and the Russian manual, with a new, scratch-built English manual, probably in HTML, which should be the first port of call for any new player. For this we will need several things:

 

Firstly, I would very much appreciate if anybody could translate the existing Russian manual, which Serge assures me is superior to the readme files. This additional information in comparison to the readme files, could prove to be a very useful resource in future writings.

Well, Russian manual is not so good (it may be a bit outdated), but it was definitely superior at some time in the past. I just wanted to say that it has a bit different style (more step by step instructions, html format). Though having some pictures in our new next-gen manual would probably improve it.

 

Secondly, it would be useful if we could establish a firm base. We are at a stage in the development where a great number of visual changes are taking place. For instance, I have heard rumblings of Nachtwolf designing the if-you-see-Kay out of a new mission planner interface. If we were to write a manual for one interface, only to have to rewrite it for a new one, to quote SEGA, "that's no good".

Well, actually that's one of the reasons why some projects never take off the ground Don't be afraid of doing some work even if you will have to rewrite it later. First, you get it done here and now and the results of this work are immediately available and useful. Second, you get a valuable experience which will help you later (rewriting some part of manual is much faster than starting from a clear list).

[Blood Angel]

The last four files do not appear to have the .txt format ending, but open nicely in notepad. Vets/those who know what they're talking about, could you tell me if there is a specific reason for this, or could we put those files into .txt or even .html?

As long as it doesn't break anything, add the txt. But having a copy could be more interesting maybe. Serge, any thoughts? You were a bit blurry on that one.

Well, the point is that I don't care much, we can keep existing files or change their names to something new (anyone can feel free to propose a new layout). Anyway, these files are only accessible for 'power users' who can find ufo2000 folder in windows program files. Right now only readme files shortcuts are added to start menu. It would be probably best to add all the important information to these readme files and to the game itself if we want the casual users to find it. For example, many games have information about the authors and contributors accessible from menu ('credits' or 'about' button) or shown in the final victory screen (fo single player games). I'm not suggesting to do this immediately for our next release, we may split documentation improvements into several iterations and do the most important work now and the rest of it a bit later.

 

Dos/unix line endings are not a problem for us as SVN handles this issue using svn:eol-style property automagically (text files distributed with win32 installer have dos line endings, files that come in the source package have unix line endings).

 

Fair dos. Things at that port of call shall be left as they are ... For the moment.

 

Basically, I propose that we replace the six different translations of the readme and the Russian manual, with a new, scratch-built English manual, probably in HTML, which should be the first port of call for any new player. For this we will need several things:

 

Firstly, I would very much appreciate if anybody could translate the existing Russian manual, which Serge assures me is superior to the readme files. This additional information in comparison to the readme files, could prove to be a very useful resource in future writings.

Well, Russian manual is not so good (it may be a bit outdated), but it was definitely superior at some time in the past. I just wanted to say that it has a bit different style (more step by step instructions, html format). Though having some pictures in our new next-gen manual would probably improve it.

 

Even so, even a rough translation could give us something to work with.

 

Secondly, it would be useful if we could establish a firm base. We are at a stage in the development where a great number of visual changes are taking place. For instance, I have heard rumblings of Nachtwolf designing the if-you-see-Kay out of a new mission planner interface. If we were to write a manual for one interface, only to have to rewrite it for a new one, to quote SEGA, "that's no good".

Well, actually that's one of the reasons why some projects never take off the ground Don't be afraid of doing some work even if you will have to rewrite it later. First, you get it done here and now and the results of this work are immediately available and useful. Second, you get a valuable experience which will help you later (rewriting some part of manual is much faster than starting from a clear list).

 

Fair play to you on this. I guess work is work, and anything's a start.

 

Right, shall I get started?

 

I'm intending that the first project should be to compile a "bible" as it were, of a manual. It shall be in English, and cover almost everything you will need

 

Steps required for this:

 

[1] We must assign team-members. Who is going to work on this - Anybody want to help me?

 

[2] We must pool our existing resources. What pieces of documentation already exist that can help us? How can they help us?

 

[3] Planning. What sections? Chapters? What information to include and which to leave out? What will the layout of the thing look like?

 

[4] Write the bloody thing.

 

[5] Code it and put it in an HTML file.

 

[7] Additional extras. Pictures? We have to decide what we need, and take some screenshots. Hotlinks? Where to? Find them.

 

[8] Proofread, check, and bung it in the package.

 

[9] Work on the next thing.

 

Any questions or objections?

Edited February 18, 2007 by Blood Angel

[nachtwolf]

Ok, the changelog is a bit scary since stable...

 

0.35 MB of pure text...

 

that's 12000 lines of log file.

 

You'd better have a look at the website's news : - http://ufo2000.sourceforge.net/

[Blood Angel]

E-mail it to me, if you wouldn't mind. I can pick and choose the relevant bits and update accordingly. [email protected]

[Blood Angel]

[i know, Double Post, evil etc. stab stab erk erk]

 

Nacht, thanks for the log. It seems that the vast majority of the changelog is taken up with modifications to filepaths. Would it be high treason to remove these?

 

Even without the stupid quantity of these filepath modifications, it's large. Our options are:

• Condense the changes in each month/week/day/released version revision to an entry each.
  
• Split the changelog into seperate files for each group of changes.
  
• Include only changes since last version.
  
• Provide a basic, bare-bones changelog with a link to a more detail changelog hosted on the net, perhaps at the sourceforge page.
  
• Any or all of the above at once.
  

What do you guys say?

[Serge]

[i know, Double Post, evil etc. stab stab erk erk]

 

Nacht, thanks for the log. It seems that the vast majority of the changelog is taken up with modifications to filepaths. Would it be high treason to remove these?

 

Even without the stupid quantity of these filepath modifications, it's large. Our options are:

• Condense the changes in each month/week/day/released version revision to an entry each.
  
• Split the changelog into seperate files for each group of changes.
  
• Include only changes since last version.
  
• Provide a basic, bare-bones changelog with a link to a more detail changelog hosted on the net, perhaps at the sourceforge page.
  
• Any or all of the above at once.
  

What do you guys say?

I'll describe how all this stuff was done up to this moment.

 

A detailed SVN changelog is available here online (takes a lot of time to open in a browser):

http://ufo2000.svn.sourceforge.net/viewvc/.../trunk?view=log

 

A summary of the most important changes can be found at: http://ufo2000.sourceforge.net (by browsing all the beta release announcements since 0.6.627)

 

If you compare the last entry from the current ChangeLog file (probably whatsnew.txt would be a better name for it) and the website (a news about 0.6.627 release), you will see that it is the same text. The idea was to have some short description about what user visible features (and also modding capabilities) were introduced in new versions of the game to be used for different announces.

 

If we were to release the next stable version now, different beta versions announces would be just verified (to be sure that we did not miss mentioning all the important contributions), combined into a single entry and appended to ChangeLog file (but again, it would be probably better to rename it in order not to confuse it with SVN changelog).

[Blood Angel]

I'm having a little difficulty understanding what you mean here. The way I read it, you're suggesting that a change of name to the changelog to something like whatsnew, and only updating it with identical information to the sourceforge site, and even then only with each stable update?

 

If so, then yeah, that sounds like a reasonable course of action.

[nachtwolf]

The paths are not changing, that's the name of the files which were modified in revision 0.7.XXXX

 

Also, the changelog I sent to you includes all and only changes from 627.

 

And what Serge is saying is : make it something like that :

 

--------------------

 

Modified in stable 0.8

 

-- new maps support

-- new units

-- new weaponsets support

-- etc.

 

Modified in stable 0.6.627

 

-- old stuff

 

Modified in stable 0.3.something

 

-- more old stuff

[Blood Angel]

Aha. So rather than updating the changelog with each beta (because we beta users actually know what's going on, we read about it here and occasionally contribute to it) we just update it with each stable.

 

Well that makes my life a little easier.

[Blood Angel]

The last four files do not appear to have the .txt format ending, but open nicely in notepad. Vets/those who know what they're talking about, could you tell me if there is a specific reason for this, or could we put those files into .txt or even .html?

As long as it doesn't break anything, add the txt. But having a copy could be more interesting maybe. Serge, any thoughts? You were a bit blurry on that one.

Well, the point is that I don't care much, we can keep existing files or change their names to something new (anyone can feel free to propose a new layout). Anyway, these files are only accessible for 'power users' who can find ufo2000 folder in windows program files. Right now only readme files shortcuts are added to start menu. It would be probably best to add all the important information to these readme files and to the game itself if we want the casual users to find it. For example, many games have information about the authors and contributors accessible from menu ('credits' or 'about' button) or shown in the final victory screen (fo single player games). I'm not suggesting to do this immediately for our next release, we may split documentation improvements into several iterations and do the most important work now and the rest of it a bit later.

 

Dos/unix line endings are not a problem for us as SVN handles this issue using svn:eol-style property automagically (text files distributed with win32 installer have dos line endings, files that come in the source package have unix line endings).

 

Fair dos. Things at that port of call shall be left as they are ... For the moment.

 

Basically, I propose that we replace the six different translations of the readme and the Russian manual, with a new, scratch-built English manual, probably in HTML, which should be the first port of call for any new player. For this we will need several things:

 

Firstly, I would very much appreciate if anybody could translate the existing Russian manual, which Serge assures me is superior to the readme files. This additional information in comparison to the readme files, could prove to be a very useful resource in future writings.

Well, Russian manual is not so good (it may be a bit outdated), but it was definitely superior at some time in the past. I just wanted to say that it has a bit different style (more step by step instructions, html format). Though having some pictures in our new next-gen manual would probably improve it.

 

Even so, even a rough translation could give us something to work with.

 

Secondly, it would be useful if we could establish a firm base. We are at a stage in the development where a great number of visual changes are taking place. For instance, I have heard rumblings of Nachtwolf designing the if-you-see-Kay out of a new mission planner interface. If we were to write a manual for one interface, only to have to rewrite it for a new one, to quote SEGA, "that's no good".

Well, actually that's one of the reasons why some projects never take off the ground Don't be afraid of doing some work even if you will have to rewrite it later. First, you get it done here and now and the results of this work are immediately available and useful. Second, you get a valuable experience which will help you later (rewriting some part of manual is much faster than starting from a clear list).

 

Fair play to you on this. I guess work is work, and anything's a start.

 

Right, shall I get started?

 

I'm intending that the first project should be to compile a "bible" as it were, of a manual. It shall be in English, and cover almost everything you will need

 

Steps required for this:

 

[1] We must assign team-members. Who is going to work on this - Anybody want to help me?

 

[2] We must pool our existing resources. What pieces of documentation already exist that can help us? How can they help us?

 

[3] Planning. What sections? Chapters? What information to include and which to leave out? What will the layout of the thing look like?

 

[4] Write the bloody thing.

 

[5] Code it and put it in an HTML file.

 

[7] Additional extras. Pictures? We have to decide what we need, and take some screenshots. Hotlinks? Where to? Find them.

 

[8] Proofread, check, and bung it in the package.

 

[9] Work on the next thing.

 

Any questions or objections?

 

Any questions or objections at all? Comments? Any input whatsoever, or am I going to be left to my own devices for this one?

[JFarceur]

I may be useful for [3], [4] and [8], mostly [8].

[nachtwolf]

I might be useful for 5. Need a template anyone?

[Sporb]

Ive got the weaponset descriptions and pics down. Ive actually made 3D copies of all the guns anyways and some monsters too

[Blood Angel]

Thanks.

 

JFarceur I officially nominate you Assistant Chief Scribe. Nachtwolf, I'm thinking perhaps it might be a good idea to write the bulk of the text, then worry about putting it into HTML. Sporb, those would be very handy, could we have them please?

[JFarceur]

So, where do we start, ?

 

I'll wait for orders.

Edited March 1, 2007 by JFarceur

[Sporb]

Thanks.

 

JFarceur I officially nominate you Assistant Chief Scribe. Nachtwolf, I'm thinking perhaps it might be a good idea to write the bulk of the text, then worry about putting it into HTML. Sporb, those would be very handy, could we have them please?

 

No. Wait till there all skinned and things first

[Blood Angel]

So, where do we start, ?

 

I'll wait for orders.

 

Do you have MSN / Windows Live Messenger? If not, it would make life easier if you would endeavour to get it.

 

Also, what time zone are you in?

 

Thanks.

 

JFarceur I officially nominate you Assistant Chief Scribe. Nachtwolf, I'm thinking perhaps it might be a good idea to write the bulk of the text, then worry about putting it into HTML. Sporb, those would be very handy, could we have them please?

 

No. Wait till there all skinned and things first

 

Righto. They're not immediately necessary, so just continue as you were.

[JFarceur]

Do you have MSN / Windows Live Messenger? If not, it would make life easier if you would endeavour to get it.

 

Also, what time zone are you in?

 

Yup.

 

I'm in GMT-5 , Montreal, Québec, Canada.

[nachtwolf]

 

Do you have MSN / Windows Live Messenger? If not, it would make life easier if you would endeavour to get it.

 

Also, what time zone are you in?

 

Yup.

 

I'm in GMT-5 , Montreal, Québec, Canada.

 

Wow... I knew you spoke french but I didn't expect you to be THAT close.

 

I'm in GMT - 5 too, Québec, Québec, Canada.

[Brick-To-Face]

Sacre bleu!

[Kratos]

Topic pinned: High priority for 0.8x stable.

[Blood Angel]

Also serves the dual purpose of giving me a continual reminder that I do have at least *some* responsibility here.

 

Well then, let's get started. Again.

 

At the moment, what I want more than anything in the world (apart from for this one girl to like me, obviously), is for even a vague translation of the Russian supermanual. Even if the paragraphs don't make any sense, I can use the heading structure to be the most informative yet witty mofo to have travelled the tubes. That'll sort things out for me no end.

 

So anyone know Russian?

Edited August 9, 2007 by Blood Angel

[JFarceur]

Nope.

 

...

 

[Blood Angel]

In this post, I upload the manual as an attachment, for an experiment.

 

EDIT: Experiment unsuccessful. How the heck am I going to translate this *****.

readme_ru.html

Edited August 12, 2007 by Azrael
Language...

[Serge]

Translating Russian manual never was the intention. It just served as an example that having html might be a good idea for user manuals. It has no problems with national charsets and encodings, can have embedded tables and pictures.

 

But right now seems like converting documentation to html is not the most important issue to solve. In addition, wiki can probably serve this purpose even better (easier to keep updated).

 

But a review of manuals and other text files to search for outdated information, missing credits, etc. is what we really need.

 

I'm sorry if this thread has caused some confusion.

[Blood Angel]

The idea behind translating the Russian manual was so that we could use its structure to erect a new manual - Wikia are certainly lovely, but good manuals are also very important for a project.

 

From the lookette that I've had, the codebase and game itself have certainly evolved, but the documents really haven't - they've barely been touched for at least three years. I'm starting to think it might be a better idea to throw it out and start again, from scratch, incorporating knowledge from existing documents; rather than trying to build upon what we've already got.

[bamb]

Copypaste stuff from the wiki at first, I think the wiki is mostly up to date and useful.

[Guest Azrael Strife]

Please (anyone) focus on the compilation of an english updated manual, I've already updated the other documentation but don't have time and haven't played this enough to make a manual.

[Intri]

I think I can prepare Polish translation of readme file or even manual (when it will be ready in English version) if you let me to do this (just show me where to find files to translate - are those ones on bugtracker or somewhere else?).

[nachtwolf]

Also serves the dual purpose of giving me a continual reminder that I do have at least *some* responsibility here.

Speaking of this, I'm sorry BloddAngel but it has been nearly a year (Feb 2007) and I haven't seen much progress on the doc, if any.

So my point is, we have to get this going. I'll probably put somebody else in charge unless I see some progress quickly.

 

I would like to remind everyone that this is a critical step towards the Stable release 0.8 and pretty much one of the last steps remaining.

We can't release the stable without proper documentation.

 

Please get this going.

 

To quote Serge :

Don't be afraid of doing some work even if you will have to rewrite it later. First, you get it done here and now and the results of this work are immediately available and useful. Second, you get a valuable experience which will help you later (rewriting some part of manual is much faster than starting from a clear list).

 

To do list :

 

English gameplay manual - Keystrokes, mission planning, hidden functions such as precise aiming and such.

- HTML with explanatory images.

If you have no HTML knowledge, write and get some screenshots to get along with your text, somebody else will format it for you.

Contents :

- How to play

- References to other files for complementary information

 

English Readme - Simplified manual with additional info, then translated to as many languages we can.

- Txt.

Contents :

- Very brief summary of changes

- How to play (simplified)

- Known issues (brief)

- References to other files for complementary information

 

Others - Authors, compilation, etc.

- Txt

Don't spend time on this until the manual is done. This is quick to do.

Edited January 13, 2008 by nachtwolf

[NinthRank]

Seeing as there's been no word on this, I kinda started writing a manualish thing. It's not very formatted, the writing needs cleaning up, it's got several "todo" notes, etc., but before I go on: is this anything along the lines of what you were thinking (sans screenshots)?

manual_en.zip

[nachtwolf]

Seeing as there's been no word on this, I kinda started writing a manualish thing. It's not very formatted, the writing needs cleaning up, it's got several "todo" notes, etc., but before I go on: is this anything along the lines of what you were thinking (sans screenshots)?

 

I think that's a very good start there!

Finally we got started with the docs.

Thanks a lot ninthRank thumbs up!

[NinthRank]

School's over now, so I can work more on this project. What details should go into the manual? Are we assuming that anyone who plays UFO2000 has played X-COM? I.e., should it say "left-click to move, right-click to look, click on the little red square to center on the enemy," etc.?

 

Here's a progress report of sorts:

manual_en_052408.zip

[Popek]

a summary of keys & shortcuts definitely

 

combat behaviour/interface

setup process

um... ill input more

[nachtwolf]

... What details should go into the manual? Are we assuming that anyone who plays UFO2000 has played X-COM? I.e., should it say "left-click to move, right-click to look, click on the little red square to center on the enemy," etc.?

 

Even if the majority will have played X-Com, it can't be assumed.

Best example being a close friend I play ufo2000 with. Also, some things work differently. (LOS, doors!!)

For the "target the red box" part, I think this is common sense so it's not needed.

However, options should be described.

Oh and since the mission planner ergonomics are so poor, this should be explained in great details.

[NinthRank]

Here's another update. Not much, but there are now some screenshots, a slight restructure in progress, and I'm also expanding the Mission Planner section.

manual_en_060108.zip

[nachtwolf]

Here's another update. Not much, but there are now some screenshots, a slight restructure in progress, and I'm also expanding the Mission Planner section.

 

Good work

 

Mission planner : As it is more important than game settings, 1.3.1 should be soldier edition, mention the CTRL-click hotkey in the paragraph at 1.3

 

Extensions : where to get them from.

 

Firearms is really well structured.

 

Don't mention bugs in the text (i.e. Flares bug), as bugs will be fixed eventually. If you want to point out the most important ones, make a troubleshooting section.

 

Keep it up, sounds great

[NinthRank]

Update: More screenshots, reordered the Mission Planner section, removed references to bugs, organized the weapon descriptions, started to organize controls. Weapon descriptions will go in the Mission Planner section, instructions for use will go in the Battlescape section. I'm working on the control panel now. I put in a link to the "Add-ons" section of these forums for extensions, but it still does not have instructions. I just noticed that some things don't look right in Internet Explorer, so I'll see if I can fix those.

manual_en_060808.zip