I brought up the animation system documentation because it is the first real example of "document before you release", which is what I would think is exactly what you want. It seems your take on what I said speaks more to a seeming distrust of Planetside (or me) on your part than any deception on mine, and that's a bit confusing to me considering your evident devotion (which we appreciate, of course).
In any case the animation system docs represent an intended new approach that, while not comprehensive, will nonetheless have an increasing impact on future releases. In other words major new features should be better and better documented *as soon as they become available*. Taking care of documenting old features is also being very actively worked on, as Jo mentioned, and big thanks go to him for that as he's taking significant time to do it, time which could be spend developing or doing other work.
Martin, since you've put your questions so pointedly here, I'll try to be as straight and clear as possible:
We've gone through multiple systems for the documentation and some bad decisions have been made (mostly by me) regarding how to do it. We have now found what we believe, and what is proving to be, a good system to handle documentation long-term. It addresses the major need for interlinked documentation that can be updated easily and quickly by multiple people (removing the bottleneck of a single person doing docs). It's also an expandable system, allowing us to add new features like video, etc. We feel it is a good basis on which to build.
Documentation has primarily been my responsibility and I have not attended to it nearly as much as I should have, plain and simple. Remember all those years of "There will be another Terragen (0.9) release soon!" or "TG2 final is coming!"? Matt never said those things because he wanted to lead anyone one, he really thought it would happen "any day now". He had good reason to believe that, but things happen.
I have never stated anything about the documentation that is untrue, but circumstances change, issues arise, delays occur. I could simply stay silent when these threads up, but I do care, I do want to help people and satisfy the desire for documentation, and I feel like it's my duty to respond when the question comes up. Perhaps it would be better if I just ignore them if I don't have a major documentation update to point to, but it doesn't feel right to me.
Lack of time is a significant limitation in our ability to document this software. There are 3 total staff at Planetside at this point. 2 of them are essentially full-time developers (Jo and Matt, of course). That leaves me to do most everything else, which includes marketing and PR, partnerships (e.g. Ranch), testing (I tend to test features the alpha testers don't necessarily dedicate the time to), web maintenance, and of course documentation, among others. My time is also somewhat limited because quite frankly Planetside does not currently support a full-time living salary for me (living in San Francisco, an admittedly expensive city). So I have to do other work and balance it with my TG/Planetside time.
Jo is now taking time to do documentation, and that's great, but it's time he doesn't spend on dev. We could debate and poll all day about what people want more, new features/releases or documentation. The obvious answer is both.
Another big problem is that neither Jo nor I actually know the most about TG. Jo knows a lot about certain elements, and can look under the hood at the code, checking code comments and whatnot, to figure out what some things may do, but ultimately Matt knows the most, by far. So there are limits to what either Jo or I can document properly and fully. Matt's time is most at a premium because he focuses on the beating heart of TG, the rendering engine, shaders, and associated systems.
Documentation is very time consuming, especially if you want to do it well. From taking screenshots and/or video, to simply writing out clear descriptions that can be understood by people who are not already experts in computer graphics, it's tough, slow going work.
On the bright side we are currently in significant internal discussion to address the documentation issue. This has been spurred largely by Jo, and he deserves major credit for taking initiative on it, though it is of course always on all of our minds. Coming out of this discussion will be increased efforts by all on documentation. As past history has shown, committing to specifics is often unwise. The proof is after all "in the pudding". So we'll see how the pudding tastes down the road.
Finally, I suppose that, as last time, you may feel that posting your concerns in this pointed manner has spurred things along and helped the situation. I want to make clear that everything I've said above is a simple statement of fact, of prior existing reality, and is uninfluenced by this thread and the pointed way in which you've chosen to bring the subject up again. I know you feel this is "the only way to get things done", but I just don't see it. We make the efforts we can and have mostly the same goals and desires as you and the other dedicated users, we're not enemies, and being adversarial does not, in my view, help anything. Speaking only for myself, frankly this approach only discourages me.
I hope that helps answer your questions and concerns.
- Oshyan
