Belgabor
11-15-2006, 10:53 PM
Hi everybody,
as most will have noticed, I created a basic tutorial for the importer. As I have some other (real life) time-consuming tasks at hand and would like to spend the time I have left working on the importer itself, I thought to make further documentation of the importer a community project and ask the fine people on Atari and Vodhin's forum for help :)
I will present you a list of documents/topics I currently think should be done. Before I do that though, please read the rules for it first. Some may sound a bit harsh, but I firmly believe that if we provide documentation, it should be done properly.
If you say you'll do it, do it. Please don't say you write something and then fade out. There are always things that can come up so you can't continue, but please tell me/us that you can't and make what you've done so far available for someone else to finish. I won't ask reasons and neither be mad if you do that.
Use correct English. No gutter language, 1337 or whatever, correct English grammar please. A few typos don't matter as I'll run it through a spellchecker anyways, but make them small enough so I can find the right word ;) Also try to keep it formal. A bit of fun is ok, but it shouldn't distract from the important things. You can use the beginner's tutorial as a guide. I'm no native English speaker as well, so I'd love to have someone with a firm grip on English grammar pointing out errors (that applies to the beginner's tutorial as well).
Create proper screenshots. I'll add a link to the clean screenshots I did for the beginner's tutorial below. If you need to create new screenshots, set them free properly (no crap arond the actual window). A good way to do that is to set your windows wallpaper to a single color, move every other window out of the way and use the Print Screen key. Then paste into a bitmap editor, crop roughly and finally use the magic wand to select everything anound the window. Then invert the selection and crop again. You can also use a utility that only captures the current window, but make sure it doesn't add a trial version/shareware watermark. Do not use a lossy image format along the way.
Mark screenshots orderly and in a changable way. Use a new layer for all things you want to draw on it and submit it in a format that supports layers (psd or xcf for example). Use text tools to write and lines/boxes to mark, no hand-drawn arrows, boxes and text (Exception: if you have real artistic talent and you know what you do, do it by hand. But be prepared to be told to redo it properly if you fail in my opinion :) ).
Use the same reddish brown color I used for the beginners tutorial. Let's have a common look and feel =) I hope you follow my advice about using layers, so if we need to change the color, we can do so easily.
What you submit will be released under a Creative Commons Attribution License (usually with No Commercial and No Deriv clauses) I'll add the respective headers when summing it all up and I don't want to ask everybody for premission when I do. In legalese: By submitting your work for this project you agree that it will be released under the License named above.
Think about linking to other parts of the documentation. This as a hypertext project, so indicate if you think it would be applicable to link to another part. Also try to see and write your topic as part of the whole. Thanks to docbook I may finally release everything as a pdf book(let) in addition to a html release on the importer homepage. It might also be turned into a help file for the importer.
Be prepared for contructive criticism.
Format. You can submit in any format you want. You should note that I will convert it to docbook format, so don't put extensive work into formatting it, that work will be lost. You would make me very happy if you already submit in docbook (article) format =) Don't ask me to explain it, that would take me longer than converting it from a format you already know. If you want to learn docbook, I can provide some links, but you probably should only consider that if you already know a bit about xml.
How to Submit. Either attach your work to a reply to this thread on Vodhin's forum or open a support request on our sourceforge tracker (and attaching it there). If both options don't work for you, I'll pm you my email. Of course you'll be credited for your work.
As you may have forgotten after my long blah blah, let me repeat, only start when you see your screen/forum name appear after the topic you applied for!
So here is the list of what I think needs to be done. You can apply for any item (document/topic/subtopic) you see here. You can also propose new topics, prefereably saying you'll do them =)
Note: This documentation project is importer centered, so do not suggest or submit modeler specific tutorials.
Complete comprehensive guide to install CS. Ok, this is not 100% importer related, but something that is imho needed. I'd prefer if a senior member applied for this, as it should be really comprehensive and go into details that the stickies miss or are hidden in replies to them (for example what files should be found in the theme subdirectory in Style\Themed). As some new CS friends are not really computer-literate, this document should also contain an introduction on different archive formats (zip, rar, 7z) and how to extract them. Also something like a how-to-proceed/what-could-have-gone-wrong if a "no sid" comes up should be included (which should go beyond a simple "reinstall").
Another thing that should be included is a list of the default (Vanilla+Soaked!+Wild!) directories in Style\Themed and the default particle effects so basically you can say if there is anything else in the respective directory it's probably form a failed install attempt. **finished**
Importer reference. Postponed till v18. This document should describe each and every control of the importer's windows. It represents what you normally expect from an included help file (and as said above, may well turn into that). Each topic should start with a screenshot of the respective window where every control is numbered (do not use letters), or in some cases control groups are also fine (eg x/y/z in the scenery settings, the matrix display). A legend for each number and a short summary what this window is used for should form the rest of the topic. Don't go into too much detail what can be done with them, that is the scope of the next document. If you don't know exactly what a specific control does, just put a '?' and I'll fill in.
Note: If a topic encompasses more than one window, please submit a separate documentation file for each.
[B]Main Window
General list. Reference for the common list interface in the Create Scenery OVL window and beyond. For the screenshot use a cut-out of the texture list from the Create Scenery OVL window, this has the most common controls. Note for everybody doing other topics in this document: do not explain every list control, instead refer to this topic. You should number and explain the whole group and every control not explained in this topic. It should also be explained why certain controls are missing.
Create Scenery OVL
Simple and advanced texture settings window including frame settings.
Matrix Editor As this is probably the least understood window, I'll accept a lot of "?"s in this topic ;)
Model & mesh settings
Effect point settings, Add light effect point, Add particle effect
Management Window & Auto Icon Reference window I think we need to document all the management windows only once. Use the Icon Reference Manager as screenshot.
Scenery settings window
Text String settings
Icon Texture & Icon Reference settings
Stall settings
Special Attractions settings
Advanced tutorials. Please make use of screenshots, but only number controls important for the task at hand.
Creating and using texture ovls
Creating working lights Should include recolorable lights.
Creating particle effect points
Creating firework launchers I don't think anyone tried this yet.
Creating working benches Vodhin
Creating billboards and scrolling signs **finished**
Creating stalls and special attractions (To be done later when they actually work)
Working with LODs **finished**
Working with transparent textures
Creating and using recolorable textures Aceana
Creating and using animated textures **finished**
Extensive discussion of texture styles Should include lots of screenshots. Take iceatcs screenshot as an example, but use a more complex object/texture.
Links:
(Incomplete) Screenshot pack (http://belgabor.vodhin.org/tidbits/docpicpack.zip)
DocBook reference (http://www.docbook.org/tdg/en/html/docbook.html)
Good & free DocBook editor (http://www.xmlmind.com/)
DocBook source of the Beginner's Tutorial (http://rct3.svn.sourceforge.net/viewvc/rct3/trunk/RCT3%20Importer/doc/beginner%20tutorial/beginner_tutorial.xml)
as most will have noticed, I created a basic tutorial for the importer. As I have some other (real life) time-consuming tasks at hand and would like to spend the time I have left working on the importer itself, I thought to make further documentation of the importer a community project and ask the fine people on Atari and Vodhin's forum for help :)
I will present you a list of documents/topics I currently think should be done. Before I do that though, please read the rules for it first. Some may sound a bit harsh, but I firmly believe that if we provide documentation, it should be done properly.
If you say you'll do it, do it. Please don't say you write something and then fade out. There are always things that can come up so you can't continue, but please tell me/us that you can't and make what you've done so far available for someone else to finish. I won't ask reasons and neither be mad if you do that.
Use correct English. No gutter language, 1337 or whatever, correct English grammar please. A few typos don't matter as I'll run it through a spellchecker anyways, but make them small enough so I can find the right word ;) Also try to keep it formal. A bit of fun is ok, but it shouldn't distract from the important things. You can use the beginner's tutorial as a guide. I'm no native English speaker as well, so I'd love to have someone with a firm grip on English grammar pointing out errors (that applies to the beginner's tutorial as well).
Create proper screenshots. I'll add a link to the clean screenshots I did for the beginner's tutorial below. If you need to create new screenshots, set them free properly (no crap arond the actual window). A good way to do that is to set your windows wallpaper to a single color, move every other window out of the way and use the Print Screen key. Then paste into a bitmap editor, crop roughly and finally use the magic wand to select everything anound the window. Then invert the selection and crop again. You can also use a utility that only captures the current window, but make sure it doesn't add a trial version/shareware watermark. Do not use a lossy image format along the way.
Mark screenshots orderly and in a changable way. Use a new layer for all things you want to draw on it and submit it in a format that supports layers (psd or xcf for example). Use text tools to write and lines/boxes to mark, no hand-drawn arrows, boxes and text (Exception: if you have real artistic talent and you know what you do, do it by hand. But be prepared to be told to redo it properly if you fail in my opinion :) ).
Use the same reddish brown color I used for the beginners tutorial. Let's have a common look and feel =) I hope you follow my advice about using layers, so if we need to change the color, we can do so easily.
What you submit will be released under a Creative Commons Attribution License (usually with No Commercial and No Deriv clauses) I'll add the respective headers when summing it all up and I don't want to ask everybody for premission when I do. In legalese: By submitting your work for this project you agree that it will be released under the License named above.
Think about linking to other parts of the documentation. This as a hypertext project, so indicate if you think it would be applicable to link to another part. Also try to see and write your topic as part of the whole. Thanks to docbook I may finally release everything as a pdf book(let) in addition to a html release on the importer homepage. It might also be turned into a help file for the importer.
Be prepared for contructive criticism.
Format. You can submit in any format you want. You should note that I will convert it to docbook format, so don't put extensive work into formatting it, that work will be lost. You would make me very happy if you already submit in docbook (article) format =) Don't ask me to explain it, that would take me longer than converting it from a format you already know. If you want to learn docbook, I can provide some links, but you probably should only consider that if you already know a bit about xml.
How to Submit. Either attach your work to a reply to this thread on Vodhin's forum or open a support request on our sourceforge tracker (and attaching it there). If both options don't work for you, I'll pm you my email. Of course you'll be credited for your work.
As you may have forgotten after my long blah blah, let me repeat, only start when you see your screen/forum name appear after the topic you applied for!
So here is the list of what I think needs to be done. You can apply for any item (document/topic/subtopic) you see here. You can also propose new topics, prefereably saying you'll do them =)
Note: This documentation project is importer centered, so do not suggest or submit modeler specific tutorials.
Complete comprehensive guide to install CS. Ok, this is not 100% importer related, but something that is imho needed. I'd prefer if a senior member applied for this, as it should be really comprehensive and go into details that the stickies miss or are hidden in replies to them (for example what files should be found in the theme subdirectory in Style\Themed). As some new CS friends are not really computer-literate, this document should also contain an introduction on different archive formats (zip, rar, 7z) and how to extract them. Also something like a how-to-proceed/what-could-have-gone-wrong if a "no sid" comes up should be included (which should go beyond a simple "reinstall").
Another thing that should be included is a list of the default (Vanilla+Soaked!+Wild!) directories in Style\Themed and the default particle effects so basically you can say if there is anything else in the respective directory it's probably form a failed install attempt. **finished**
Importer reference. Postponed till v18. This document should describe each and every control of the importer's windows. It represents what you normally expect from an included help file (and as said above, may well turn into that). Each topic should start with a screenshot of the respective window where every control is numbered (do not use letters), or in some cases control groups are also fine (eg x/y/z in the scenery settings, the matrix display). A legend for each number and a short summary what this window is used for should form the rest of the topic. Don't go into too much detail what can be done with them, that is the scope of the next document. If you don't know exactly what a specific control does, just put a '?' and I'll fill in.
Note: If a topic encompasses more than one window, please submit a separate documentation file for each.
[B]Main Window
General list. Reference for the common list interface in the Create Scenery OVL window and beyond. For the screenshot use a cut-out of the texture list from the Create Scenery OVL window, this has the most common controls. Note for everybody doing other topics in this document: do not explain every list control, instead refer to this topic. You should number and explain the whole group and every control not explained in this topic. It should also be explained why certain controls are missing.
Create Scenery OVL
Simple and advanced texture settings window including frame settings.
Matrix Editor As this is probably the least understood window, I'll accept a lot of "?"s in this topic ;)
Model & mesh settings
Effect point settings, Add light effect point, Add particle effect
Management Window & Auto Icon Reference window I think we need to document all the management windows only once. Use the Icon Reference Manager as screenshot.
Scenery settings window
Text String settings
Icon Texture & Icon Reference settings
Stall settings
Special Attractions settings
Advanced tutorials. Please make use of screenshots, but only number controls important for the task at hand.
Creating and using texture ovls
Creating working lights Should include recolorable lights.
Creating particle effect points
Creating firework launchers I don't think anyone tried this yet.
Creating working benches Vodhin
Creating billboards and scrolling signs **finished**
Creating stalls and special attractions (To be done later when they actually work)
Working with LODs **finished**
Working with transparent textures
Creating and using recolorable textures Aceana
Creating and using animated textures **finished**
Extensive discussion of texture styles Should include lots of screenshots. Take iceatcs screenshot as an example, but use a more complex object/texture.
Links:
(Incomplete) Screenshot pack (http://belgabor.vodhin.org/tidbits/docpicpack.zip)
DocBook reference (http://www.docbook.org/tdg/en/html/docbook.html)
Good & free DocBook editor (http://www.xmlmind.com/)
DocBook source of the Beginner's Tutorial (http://rct3.svn.sourceforge.net/viewvc/rct3/trunk/RCT3%20Importer/doc/beginner%20tutorial/beginner_tutorial.xml)