[Fineus]

Hey all.. I may be way off the mark with this one - in which case let me know - but it seems a lot of people aren't sure how to turn on / off certain features of the source code.. or indeed what parts of the code are packaged with what *.exe file (the engine trails code change may come with glows and HT&L enabled, it may not - who knows but the person who produced it?).

My point is this.

Would it be possible to package a readme file with all releases of the code, including whatever changes are made from the original source as well as any commands necessary to run the code (or indeed where files need to go etc. to make use of the features it brings. I.E. Ships glows textures go in the effects folder).

It's not a massive thing, it just helps people like me keep track of what code is packaged with what mod and so on... so that if I want to try something I can know exactly what is / can be enabled and how to do it.

Indeed there could be a generic readme section on the website that contains each addition such as:

Glow maps:
These add glow effects to all lit elements of the ships. Glow maps should be placed in the /data/maps directory of the base FS2 folder.

Engine trails:
These add additional trail effects to engines of all ships in game. Textures should be placed in the /data/effects directory of the base FS2 folder.

Engine Particles:
Adds particle effects to ships engine in game. Use the following .TBL entrys to generate the code:

CODE

And place all textures for particles in the /data/effects directory of the FS2 folder.

Developers could cut/paste these into their readmes and add on their own changes at the beginning and/or end. End users could download the file, open the readme to see whats there and immediately make use of it.

Possible? Waste of time? It'd be really handy for the likes of me!

[Flipside]

It would be useful to have a 'Bible' for the SCP, I think a couple of people are working on one, but because it's a WIP, it's constantly being updated.

Flipside

[Terorist]

Such a documentation would need to be online and very easily accessible to all contributing to the SCP. Whenever something gets added or revised, it should be added to that documentation when committing code. I think a wiki might be a solution for this, if it's not going too overboard. At least it'd be easy and very very quick to edit. Some publicly available plain text document is, umm, lighter, but a clumsy way...

http://c2.com/cgi/wiki?RunningYourOwnWikiFaq

[karajorma]

I think poor documentation is one of the biggest problems with the SCP.

There are lots of features that people don't use cause they aren't sure how.

The documenting features
thread is a step in the right direction though.

[Sticks]

Any one of you are welcome to start a documentation project up...



We're bogged down in graphicky mothballs right now

[bottomfan]

I know Ive not been much help lately. But things are moving along, just not as fast as I would like.

The Wiki (Tiki, or some multiauthor service) would be the ideal here. There's of changes being done, If you subscribe to the CVS mailing list you'l know what I mean.

Goober, whats your say on this?

[Flipside]

Well, the best way, I guess, if for each person to take one subject and be responsible for finding as much as possible, for example, one person might do the new sexp's, another the new graphics facilities and a third might take on new table entries etc. That way people won't be repeating other peoples work But the SCP guys do realise this will include annoying PM's about 'what does this mean?' etc? It would have to be done as though to a complete noob though, since it would need to be as accessible as possible

I'm willing to help, since I will be one of the people benefitting from the information
Flipside

[Sticks]

I'd be willing to field emails about this stuff. It would probably expose some dumb decisions that have been made too.

[Goober5000]

I always thought the readme folks (bottomfan and whoever else) should be in charge of documentation... they'd do the research and interview the coders if they can't figure something out.  There are plenty of threads with explanations on how to implement features, but they're scattered all over the forum and most coders don't have time to look for them.

bottomfan, if you wanted to get a documentation team together, we'd back you up on that... give you avatars and everything.

[Taristin]

Hell, if all it is is searching the forum, that's easy... even I[/i] could probably do that...

[WMCoolmon]

Searching the forum and rewriting the information in an organized, concise, and easy-to-follow style. Which it won't be in. Oh, and including code samples, examples and/or screenshots.

[Flipside]

Basically, a user manual. You'd be amazed at how much we all know as a group, that we never bother to write down, because it seems so obvious. What I think Kalfireth is looking for is an easy to read document that anyone can pick up, and be able to turn to a particular page and look up an index of, for example, sexp's and read a detailed description of it, it's format and what each variable for the sexp describes, so it will be quite an endeavour!

Flipside

[Terorist]

A wiki would be easy to modify by anyone (and I mean anyone) noticing room for improvement... Even if it's just a small point, all that would eventually add up - and when it's more or less up to date, keeping it that way won't be taxing at all. If a coder doesn't have time to write there about a new feature himself, there will be hordes of fans that'll race to do it for him as soon as it's introduced... that's the usual effect in these things.

[redmenace]

bottomfan, I will take up a section on getting started and using CVS

[Flipside]

People do realise this will probably become ending up a complete Freespace 2 modding manual?

Ah well.... I'll take on the new graphical effects and the relevant command line instructions for activation/control if you want?

Flipside

[redmenace]

yes exactly, what i was thinking. i mean people will need instructions on how to make glow points for example.
Now is a modding manual really all the wrong? If you are concerned about that we could write 2 different ones. But a modding mannual for the SCP is a project in an of its self. We could through together the resources we have already. I mean we have a tutorial on modeling over at Volition Watch, a PCS tutorial also somewhere, a totorial on nameplates for the orion. We could just collect all these resources and bring them all together.

[Flipside]

More or less, yes, but what it would really need to make it accessible would be for one person to read it all through and get text re-written when neccesary to make sure everything makes sense. For example, some people call them points, some call them vertices, a lot of people get these confused with paths etc etc... So language throughout would have to be consistent. Theres going to be terminology clashes between glowmaps and over-exposure etc as well.

So it would probably mean grabbing these tutorials, reading them and then re-writing them in your own words, crediting the original author for reference work.

Well, that's my opinion of what you would need anyway

Flipside

[redmenace]

well yes. but the beneft is that we would already have the graphics. But then this would be a good new project for HLP. This would be of work. we would have to have to cater to people using different programs. Such as adobe photoshop and PSP.

[Bobboau]

the PCS thing is in my sig

[redmenace]

well its a start.