Severe need for documentation

Started by PabloMack, April 18, 2010, 01:25:43 PM

Previous topic - Next topic

N810

You do know that this is a very small comapany right..?
Hmmm... wonder what this button does....

timj

#16
Perhaps too small? Considering the number of users/customers and considering the importance of this program in the terrain rendering field, perhaps it might be an idea to get more people involved in developing it. It's such a good program that there must be some willing investors out there.
Just a thought - not a criticism.

acolyte

I've been tracking this company for a long time. I understand its small, but considering the user base it has and that its now been tracked being used on blockbusters such as Gi-Joe, it's not an unreasonable request to provide documentation, or even suggest they get on the ball and hire some more people. It's not our fault their small, and if they are maybe they shouldn't be.

otakar

It seems to me that since the resource allocation towards documentation on the part of PS is not likely to change dramatically, the Wiki approach lends itself best. Utilize the user base to expand and enhance the documentation, create examples and document findings. What I'd like to see is context-sensitive help pointing to specific Wiki webpages (so that you can click on a help link in a node for example). Basic node information could be followed by further-reaching help, more in depth discussion of available parameters, and there could even be links to specific threads on the PS forum. Of course, there are challenges to keep this collection of material up-to-date and somewhat organized, but you could again enlist the help of users - fulfilling sort of a moderator function common across discussion boards and the like.

While I find the forum indispensable, with its growth it is becoming harder to recall specific discussions and find the info you know has been posted at some point in time, despite all efforts to categorize and merge. This is only going to get worse I am afraid.

PabloMack

We have here a sort of catch-22 situation.  PS knows that new-hires (even considering that money is not a problem) are going to have to get up to speed.  This puts more strain on those who know how the software works.  I, for one, would be delighted to write a book on TG.  But I am a relative beginner so I need information from PS to bring me up to speed.  I need documentation.  See the dilemma?  Knowledge necessarily has to trickle from the designers/implementors down to those who write documentation.  And the best way to do that is for them to write documentation for internal use in combination with some sort of internal education program.  This all takes time away from development.  But when you are chasing a changling, it makes it all the much more difficult.  Anyone care to elaborate on how much TG2 has diverged from original TGC?  This might give us a guide on how much TG is changing thru time. 

Tangled-Universe

#20
Quote from: PabloMack on April 21, 2010, 05:52:10 PM
We have here a sort of catch-22 situation.  PS knows that new-hires (even considering that money is not a problem) are going to have to get up to speed.  This puts more strain on those who know how the software works.  I, for one, would be delighted to write a book on TG.  But I am a relative beginner so I need information from PS to bring me up to speed.  I need documentation.  See the dilemma?  Knowledge necessarily has to trickle from the designers/implementors down to those who write documentation.  And the best way to do that is for them to write documentation for internal use in combination with some sort of internal education program.  This all takes time away from development.  But when you are chasing a changling, it makes it all the much more difficult.  Anyone care to elaborate on how much TG2 has diverged from original TGC?  This might give us a guide on how much TG is changing thru time.  

This sounds a bit as circular reasoning to me.
Needing documentation to be able to write a book. You're absolutely right, but to a certain maximum extent I'd say.
If it would only be because of documentation then everyone could write a book about anything, without needing any experience with the subject.
In 3D software packages like these a good book distinguishes itself from a regular book by mainly the experience of the author with the software-package and how well he's able to transfer his knowledge to the reader. The latter is dependant on the author's writing skills.

As said before the documentation is being worked on and all the information available can be found here in these forums.

So far I find the majority of your questions very advanced and way beyond the scope of a "relative beginner" as you describe yourself.
I'd say start at the beginning.
I tried to motivate you before a couple of days earlier that the best way to learn TG2 is to spend time here reading the tutorials, going through file sharing and for example reading NWDA contest entries, since these contain a lot of tips about anything.
In the meantime you could actually start using TG2, render images, post these here, explain what you tried to make and what you still want to achieve.
Ask for help and lots of people will try to, including me.
This is the best advice I can give you.

This may sound harsh, but isn't meant to.
It's best to skinny-dip first into TG2 :)

Cheers,
Martin

nesthead

The problem of documentation has been going on for so long now that most people seem to have accepted that discovering how the system works is part of the fun of owning the software.  This and the 12 month wait for the final(ish) version to be released the other year, have been part of the Terragen experience for me.  As I have said before, anyone who bought Terragen should have factored in the delays and the lack of documentation to their purchase decision. I don't get angry because I enjoy what I can do and learn from the people who know what they're doing and are happy to pass it on in this forum.

However, you can't get away from the fact that documentation was promised as part of the package and it has not been delivered.  This is frustrating even for me but it must be so much worse for people trying to earn a living. 

Whilst the loyalty and knowledge of the user base is impressive it should not be used by the company as a free source of the documentation that should be part of the package. 

PabloMack

Quote from: Tangled-Universe on April 21, 2010, 06:54:38 PM
This may sound harsh, but isn't meant to.
It's best to skinny-dip first into TG2 :)

Cheers, Martin

It doesn't sound harsh at all.  Thank you for being so kind.  Right now my TG2 machine is tied up doing a LW render for a paid project.  I estimate that it will take about 9 days total and I have about 5 days of progress.  Besides that, I have two TG2 renders going on (same machine) put on low priority.  One is an HD high quality still and the other is a low-res low-quality animation to see what TG2 can produce.  It will probably be a week before all programs have finished.  But then I have to start the next LW paid project.  So in the meanwhile, I am trying to study TG2 without using the software.  I can't afford to crash either program so I am reading what I can with docs that are available.  I am looking forward to doing some of these tutorials you talked about.  

gregsandor

A lot of what the program does is described in the release notes for each version, posted here in the forum.

FrankB

guys, I think the point is well taken. I believe this particular thread has already had its impact in bringing documentation a little bit further up the priority list. Everyone agrees, including PS, that the situation around documentation must improve soon, and not next year. But still give it some time to progress, it's nothing one can complete over night.
As some of you have already considered in their posts, besides the 2 programmers, there is only Oshyan for support, documentation, PR, forum management and whatnot. I guess what I'm saying is that personally I am positive that it will come, and has to progress soon, but some patience is still needed.

In the meantime, it's not that there are *no* learning resources, in fact there are quite a lot out there. Just scattered, but not unfindable (is that even a word? ;) )

Cheers,
Frank

Oshyan

We're a small company by choice. We've made the conscious decision not to become answerable to investors who - in general - only have a profit motive. That has limited our ability to grow of course, but it's a worthwhile trade-off for us. We are growing organically (1 new employee every 3 years on average so far, I think ;D), and plan to continue doing so. We also charge a lot less for our product than many other companies would, and we offer a free version. These kinds of policies probably wouldn't be very popular with stockholders.

I certainly regret the lack of documentation, but it definitely wasn't an "afterthought". In fact I spent quite a lot of time prior to the release on creating what we have so far and simply haven't had much time to do any more since. I should note here that what is currently publicly available is actually not totally current due to some recently discovered oversights. In any case I have started to invest more time recently in docs and I think the move to a wiki and my increased focus should yield much improved results soon. Until then we can only ask you to be patient.

Live links to documentation are planned, once we have sensibly named online documentation links (e.g. node-name derived, rather than "page1.html").

It's not as if we plan to "use" the community as a sweat shop to write documentation for us. We're aiming for collaboration, which is a great part of our existing community and the helpful spirit that the forums here present. We'll do what we do best, describe the way the program works. Users will do what they do best, describe how they did a particular thing, or add information about what a specific range of settings might do, etc, etc. It's win-win. And anyone who doesn't want to contribute doesn't have to. If nobody wants to contribute, we'll put all the information we can in there and that will be that. Better a "living" documentation than a static, printed book if you ask me.

Anyway, I think the subject is well talked out. We're workin' on it! ;D

- Oshyan

Henry Blewer

There are generally enough changes between versions, so that detailed docs would require a large effort to re-write the docs. Maybe a bit more detail on the new and changed features would be better.
http://flickr.com/photos/njeneb/
Forget Tuesday; It's just Monday spelled with a T

acolyte

Oshyan, I want to thank you for, as always, being forthright and up front with everybody here. You rock! That said, I fully acknowledge PS's right to stay small and avoid the corporate swamp out there, but if a new staffing member is being brought on every 3 years, then may I suggest thinking about hiring some of the Terragen vets around here to come in for a few weeks to a month and knock some of this stuff out? A hodgepodge of questions and answers on the forums is only going to make things more spread out in terms of finding "documentation". If you guys at PS need help writing docs because your small, then please consider hiring on seasonal workers at a lower cost and getting this rolling. Not to mention, if it worked well, maybe you could do this once a year, pick something really dev-worthy to go after and knock a new feature out with a small group of coders over the period of a month or two instead of years at a time.

Oshyan

Hiring people short-term would work well for documentation (if they were already very familiar with TG2 of course), and perhaps a few *very* isolated features, but generally speaking just getting into a new app's code base (or the changes year-to-year if you only work a couple months a year) would take enough time that it's pretty impractical to try to do a "seasonal work" type of thing for coding. But again for docs it's not a bad approach. It's something we've considered in the past and will continue to keep in mind.

For now we have a plan for taking the next step and we'll see where that leads. If progress is not rapid enough, we may indeed have to hire someone on contract to help out.

- Oshyan

airflamesred

Its a fantastic program and I must say, In these times especially, the perfect example of how a company should be run.
Althogh the lack of documentation is well documented shall we get on and produce some images. I struggle with some elements of TG2 but in a years time I feel sure I won't.