Quote from: Oshyan on March 13, 2012, 03:51:26 AM
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).
Quote
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.
Do I understand correctly that my >2 year old suggestion on the alpha forums to document "as you develop" is now being effectuated?
So, next time when someone complains development is slow you're saying it's because of documentation and if someone complains about documentation it's because of development?
Come on.
Quote
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.
What system are you talking about? If you want to convince us and give us a general feeling of that things are getting right I think you should be less "vague" and more to the point.
As a starter usually a good system is writing it all down (needs to be done anyway) and then PDF. Has that been done? Everything is documented and only needs to be ported to this yet unnamed documentation system?
Quote
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 appreciate you admit you have your part in this documentation misery, but I don't feel you should feel that guilty. Unless things are indeed written up completely/PDF and only need to be ported, but somehow I'm unfortunately so sure that that's not the case?
Quote
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.
Absolutely true that you have never said anything untrue and that's not sarcastic. However, what is a little bit sarcastic is; what's not true about saying for years on that you're working on it and that it has planetside's 'attention'
I say those things to my boss too, but actually only when I feel like doing something I like better. See?
I again appreciate your honesty and the fact that you do care and feel it is your duty.
If you don't feel right about it, why not try to fix it?
This redirects us to the line above. You do feel uncomfortable by it, yet you have the decency to respond to it, which I find one of your strongest personal assets.
However, for years the message has been the same like I pointed out above.
Quote
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.
I know about Planetside's resources. This comes up everytime and like I pointed out in my starting post I was hoping to see other arguments than the regular "resources excuse" etc.
As you can read here below it has to do with a business model and ideas how to approach planning these actions of development/documentation/TG2 promotion by feature film work by Matt. With right/careful planning and discipline you can develop and document along. That's easier said than done, but if it doesn't work then it's one of those 2 things disturbing the process.
Quote
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.
I've answered to that already above. Circular argumentation.
About the poll: you should have understood the message I gave by saying that. Of course I'm not going to start a poll, duh
Below I can read that after internal debate Jo decided "to do it" and this rather comes to me it has been a choice because of the lack of progress in documentation which wasn't his responsibility initially.
So I'm not sure where you're really going by saying this.
Quote
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.
Quote
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.
Yeah I happened to make a couple of tutorial and 4000+ messages in the past 6 years with an on average hour a day or so online.
If I'd bundle it into a book it would be pretty thick, almost as thick as a regular manual
Yes it's tough and slow work, but with planning/dedication/discipline like I pointed out before you can write/do a LOT in 6 years.
Quote
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.
Here you go again. Seriously, you should consider stopping with spoon-feeding these messages to people by making promisses again and again and again or by giving people only an impression things are moving. History shows that the outcome is otherwise.
Quote
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
Thanks Oshyan.
Unfortunately it seems that the people of this forum, including the more dedicated openly communicating ones can't get to you guys at Planetside as evidenced by you saying
Quote"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".
Basically this means we can think/say whatever we all want in what way we want, nothing will change.
And you're complaining this makes Planetside look bad, what I'm doing here?
All the users here have tried EVERYTHING and in ANY WAY in the last 6 years.
The first time here I start a long considered message about it here, and although you may not like it how I do it, it's definitely not again
I find this conclusion really disappointing.
Please everyone help me understanding the last quote in any other way than what I'm thinking now, thank you!
Cheers,
Martin
