Severe need for documentation

[PabloMack]

My heart goes out to all the TG2 users who feel like they are wandering around in the dark, because they are.  Now I understand why so many of you hang out here in the forums because you are in great need of documentation that describes how the software works.  I have decades of experience writing technical documentation and I know it takes a temendous amount of work but someone has to do it.  In my opinion, if good documentation existed for this product, there would be a lot more people using and buying it.  In my experience, artists are not very good in general at describing things.  I just went to a local 3D users group meeting in the Houston area and I wanted to pull my hair out listening to this guy trying to describe how software works and he is talking like someone describing the bouquet of wine.  I am not asking anyone to walk me through what I want to do.  I just want good documentation describing how TG2 works so that I can figure out how to put the pieces together to build something that will generate the images I want.  Let me just give a very small example of what needs to be in the documenation.  Below is an image of the default planet node in the node view:  

[attachimg=#]

It consists of a rectangle with two triangles on top facing down and one triangle on bottom facing down.  I have figured out without any documentation that the two triangles on top are inputs to the Planet Node and the one on bottom is an output from the Planet Node.  All the documentation says is to connect the nodes together without much explanation of what is happening and why.  

In the default scene, if I take the Base Colours Shader output (which is connected to the top triangle on the left) and the Atmosphere 01 shader's output (which is connected to the top triangle on the right) and swap them, the rendered image looks different.  Why?  There is nothing in the Node Reference that even mentions these two inputs in the Node View and why the left and right one are different.  And why is the bottom output triangle of the default planet node not connected to anything?  But we still get an image.  Why?  It would seem that the planet node has to be connected to the input of the render camera but it isn't.  Looks like intuition doesn't gain us very much in understanding here.  So we must have documentation.  

Some information comes in the form of the way nodes are connected in the default scene.  And what are these lines between nodes communicating?  Should we think of them as scalar elements where the node network is like a collection of expressions that are computed once for each pixel element in the final scene?  What should we think of them in terms of their data types with respect to the kind of information they are communicating?  Are they different for different node types?  Some of their titles imply this but not much more than that is said.  And where are all the inputs and outputs of other nodes that are not part of the default render documented as "Left input does this", "middle input does that"  etc.  The Node Reference really contains little more than a screen shot and a few sentences about what the node is in general.  That's it!  Anyone will need a lot more than that before they can expect to understand and make use of a software package as powerful as TG2.  I, for one, belong to many forums and I am not enough people to just hang out in all of them all the time.  We need better and more complete documentation.  

[airflamesred]

I would agree with you there Pablo. Having said that everyone else seems to have worked things out on their own. I'm only using a small laptop so any experimentation takes ages to render and so I'm learning at a very slow pace. Not ideal.
It appears Planetside are working on it though I would have thought there is a market out there for someone to write a book.

[Tangled-Universe]

First of all I really agree with you about the whole thing on documentation. There's some, but way from complete and/or not detailed enough. If I remember correctly Oshyan recently told you that an overhaul of the documentation is in the making.

You have probably been told by others to just get started, read and walk through the available tutorials, surf the file-sharing sections etc. I guess you've done pretty much of that already, but believe me. They're right.

However, I have been following your posts here from the beginning and one thing I noticed, and I don't want to sound like a dick, is that a lot of questions are things someone would wonder about when they are advanced with the software or either are things which you shouldn't think about too much. Your example of that connecting the atmo-node to the terrain input of the planet gives a different result from the way you're supposed to connect them is to me common sense. When it says "surface shader" it means you should not connect the atmosphere to it.
And yes, you're absolutely right: what kind of information is passed through the nodes? I really can imagine you want to know, I'd too, but I don't mind it too much, because I can often get the result I'd like to achieve.
The reason for that is in alinea 2.

Asking questions is absolutely good and no problem, but with lacking documentation and tons of unsorted info here the one and only best way of learning quickly is getting started and post images
So I'd say get started with your scene, or if you already did then finish it, post it at the image sharing and ask critiques/advice.
Knowing the ins and outs of any piece of software will not guarantee satisfactory/expected results.

Looking forward to see your first work!

Cheers,
Martin

[Eikers]

I have just started off using Terragen, so it is very easy for me to agree on that the documentation is sparse. I have learned a lot the last few weeks on how the software works through following tutorials and examining clip files. There are many advantages to this kind of hands on approach and it works quite well with an outstanding user forum such as the Planetside Forums to draw knowledge from.

I do however feel that the lack of documentation slows down the learning process. One 'simple' suggestion would be to make a better description of each node; what does it do, what can be connected to it, and what is it's output in terms of data types. For example: you cannot connect whichever node you please to another, there are restrictions to this probably due to data type definitions in the software. Such fundamental definitions need to be available to the user in order to develop skills more effectively.

[PabloMack]

Thanks, you guys.  Don't get me wrong.  This forum is the best bunch of guys I've ever hung out with, really (I brought a six-pack. Where's the 'frig?).  Oshyan and cyphyr and everyone else have been so nice and helpful. I wouldn't dare want to mess with a good thing.  Oshyan explained that they want to stay away from writing documentation that tell you specifically how to do this or that.  As I understand it, Planetside wants documentation to give us an understanding of how the sofware works so we can be more independent in figuring out how to get things done on our own.  But it looks like the way everyone is learning how to use the software is to go thru tutorials showing us specifically how to do this or that which seems to me to be the direction Planetside wants to get away from (at least for advanced users).  So this brings us back to learning by "specifically how to do this or that".  I am getting de-ja-vu all over again.  I guess it boils down to the principle that quality (like wine) just takes time.  (I want patience and I want it NOW!)

[FrankB]

"how to do this or that" is probably a too open-ended path for the planetside documentation. However, as you rightfully say, everyone seems to want to learn that way. Which is why there are so many tutorials around. This is also why Planetside has created the user wiki, where everyone can contribute. Sadly though, not a great many people are growing the wiki. Still it is growing, and will be growing, and is a quite good resource already on "how to do this and that".  http://www.planetside.co.uk/wiki/index.php/Main_Page
I don't know if you are aware of the wiki, but there are a lot of nice gems in it, ranging from video tutorials for beginners to some advanced stuff.

Still there is potential (I think) in writing a book on TG2 like in the dummy series. Unfortunately someone would have to pop up that has the writing skill, the time, and the TG2 knowledge to make a good book - which hasn't happened, yet. But there's still hope

Frank

[Dune]

I think it is very hard writing a complete book on how things exactly work and what does what, as so many 'procedures' are still to be invented. Things can be accomplished in many ways, sometimes totally unexpected combinations do the trick. And I think that's the fun of TG2. I wouldn't want to know it all from a book (and miss the exchange of ideas, and help in this community). But that's me. I guess a lot of people would want a quick 'how-to' and produce an image. It would benefit the sales of TG2, that's probably right.

---Dune

[PabloMack]

I did "discover" that the input and output triangles are labelled, for if you hover the cursor over one of them, a little popup identifies it.  I think most of this sort of "documentation" has to be discovered by working with the software.  The "Your First Scene" document avoids talking about nodes so that it doesn't scare off new users. 

[Oshyan]

As I said in the other thread on doc issues, this is a problem we're painfully aware of and are working to address it. It's a slow process, as anyone who has ever written documentation for a complex piece of software will know. Anyone who has not attempted to document an open-ended node-based application will not quite have an understanding of the full difficulty, even if they've done other complex documentation. This approach presents its own unique, additional challenges.

In any case, some of what you point out *is* already partially or fully documented, e.g. in the in-forum ("archive") docs section. For example the node network connections are covered in the incomplete node ref section of the User Guide:
http://forums.planetside.co.uk/index.php?topic=20

I realize that pointing this out doesn't speak particularly well for the state of the docs, but that's already well understood. I should also acknowledge a difficulty there in that the forum docs may now be mostly overlooked because users are advised to reference the Help page on our main website, where only the 1st part of the User Guide can be found. This is the result of an incomplete move to a new way of providing the docs (as printable PDFs), and I have to take responsibility for not having finished this before. All I can say is it's something I'm actively working on.

The node reference is also incomplete, and actually the version that is available right now is much more incomplete than internal versions have been for some time due to a rather serious oversight. Again I have to apologize for this. The state of things with the docs is something I'm very unhappy about, and would like to resolve immediately. Unfortunately everything takes time, and there are many other things going on at the same time which make progress even slower.

Our current goal is to publish all the information we have so far written, and then allow the community to help us improve and maintain it. We realized this was necessary due to the ever-changing nature of the application, such that docs that were written a year or even 6 months ago, may not now be entirely accurate, or certainly cannot be comprehensive as new features are added.

For the time being I hope you'll be able to find the information you need and we will do our best to answer your questions. When the docs are transferred to the wiki, I hope you'll consider contributing some of what you've learned.

I suggest starting a new thread for any remaining application questions you have, not related to the state of the docs.

- Oshyan

[Henry Blewer]

I agree with Oshyan. I've been having an awful time writing a tutorial for the canyons tgd files I posted. My gibberish makes sense to me, but my knowledge of the program is largely intuition. Explaining why and how something works is a real chore.

[Marcos Silveira]

I would surely buy books with a title like that:
"Terragen 2: Basic to Advanced technics" or
"TG 2: Tame the Functions and Make Them do What You Want"!!!!!!

Or whatever Luc would put in a book about TG 2!!!!!

[Tangled-Universe]

Ghehe, that would be a one-page book then lol

A couple of guys here, me also, have once been approached by a publisher about writing a TG2 book.
We never heard of him anymore actually.
He probably became aware that it is not as easy and straight-forward to write a good book for TG2.
Probably for reasons Oshyan already mentioned here.

I certainly would like to help with documentation, but I'm not sure if I have the writing skills (english is ok, but not that good) or that much understanding of the software to be sure about everything I will write down is really correct.

[dandelO]

Martin, you're usually very concise in your descriptions and demonstrations, I think you're exactly the type of user that would greatly benefit the documentation sections of TG.

[domdib]

And there are a few native English speakers here whom I feel sure would be happy to correct any perceived infelicities of expression 

[acolyte]

I am so ready for complete documentation. It sucks that this has been an afterthought. And I don't see why getting result-specific in the documentation can ever be perceived as a bad thing. People buy Terragen to produce images or animations that are specific to nature. Pretty sure no one's going to be doing any character animation with it soon. Sure it's a nice idea to keep things in general terms so that people reading the docs aren't locked into only creating one type of mountain, but come on. I would gladly trade a solidly worded tutorial (with pictures) that walked me step by step on how to create a specific scene for any of the incomplete and vague documentation floating around any day of the week.

That said, there are a few really good tutorials on Terragen made by the advanced users which really help. It seems to me that the user-based community has spoken, and that in lieu of having fully completed documentation by the devs, they're willing to take up the reigns and provide tutorials on the web.

Terragen is such a massively complex piece of software, that I don't see how it would be possible to write a book on all of the nodes and how they function. Given that those nodes change function from month to month and that each node can produce completely different results based on their implementation into an overall node network, it seems like even if we had documentation differentiating what all the different nodes do, it would still be incomplete without a vast array of user generated tutorials describing what's going on under the hood.

How many people have bought this software with the hopes of just being able to generate a snowy mountain, an early morning fog over a lake, or a desert canyon? There are plenty of standardized looks that need to be achieved as starting points for experimentation which have to be recreated each time someone delves into the software. A step towards resolution for this can be found in the NWDA packs which are available (at additional cost); however, if Planetside is going to ask someone to pay more than a couple of hundred dollars for a piece of software that is supposed to be specialized for generating realistic nature scenes, then if they're not going to have presets, then the very least they can do is get proper documentation out to door. And this documentation needs to be what the community wants and is looking for and not what Planetside thinks is best.

Sorry if this comes off as harsh, I don't mean it to be rude, but this is ridiculous. Planetside, either hire more staff to help with what is a seemingly overwhelming task, or prioritize what needs to be done better. We're probably going to be waiting a while for the next big thing to be released again anyways right? Documentation for what is already here should be priority.