TDN is up with T2d Section
by Darren Stuart · in Torque Game Builder · 10/08/2005 (2:11 am) · 33 replies
tdn.garagegames.com/wiki/Torque2D
how cool is this.
I won't ruin the surprise of whats over there but it makes the documentation issue a thing of the past.
lots of guides of creating sorts of games
Platformer Game Basics is just one.
I got this from Ben's plan www.garagegames.com/blogs/8863/8889
how cool is this.
I won't ruin the surprise of whats over there but it makes the documentation issue a thing of the past.
lots of guides of creating sorts of games
Platformer Game Basics is just one.
I got this from Ben's plan www.garagegames.com/blogs/8863/8889
#22
However coupled with the lack of news or updates on the engine it can get frustating from a user point of view.
You guys might say yeah but we have this to do and this and that but we don't know what your up to and thats why the plans are so important.
I'll be honest Stephen I have seen your responses to peoples questions and you do come across as a bit harsh sometimes (something you should work on).
however this is the problem with the written forum people often come across as agreesive or overly crictical when its not there aim at all.
10/10/2005 (10:16 am)
I'll chip on this. what I have seen on there is really good. I think the level of the stuff on there is bang on.However coupled with the lack of news or updates on the engine it can get frustating from a user point of view.
You guys might say yeah but we have this to do and this and that but we don't know what your up to and thats why the plans are so important.
I'll be honest Stephen I have seen your responses to peoples questions and you do come across as a bit harsh sometimes (something you should work on).
however this is the problem with the written forum people often come across as agreesive or overly crictical when its not there aim at all.
#23
10/10/2005 (11:06 am)
TDN is friggin cool! The Docs have come a loooooooong way since I originally joined/purchased in 2002. As always this community will improve everything about TDN.
#24
The only suggestion I'd make is that from working on the Unreal wiki I can say that it's always interesting to have user-orientated areas for people to post code examples which can later be referenced or sucked into tutorials. Things less structured than real tutorials. Tutes can be really hard to write well (not sure I ever really got it down) and if there is a section or such that people feel comfortable not writing extensively it can create a kind of undercurrent of contribution which really helps a dev wiki moving.
10/10/2005 (11:53 am)
Just browsing through it and this looks amazing. Great job to those involved.The only suggestion I'd make is that from working on the Unreal wiki I can say that it's always interesting to have user-orientated areas for people to post code examples which can later be referenced or sucked into tutorials. Things less structured than real tutorials. Tutes can be really hard to write well (not sure I ever really got it down) and if there is a section or such that people feel comfortable not writing extensively it can create a kind of undercurrent of contribution which really helps a dev wiki moving.
#25
EDIT: Duh, I forgot that some wikis use that for user communication. More of a scratchpad type thing was what I was thinking.
10/10/2005 (11:58 am)
... would the "My Talk" be used for something like that? Or what is that setup for?EDIT: Duh, I forgot that some wikis use that for user communication. More of a scratchpad type thing was what I was thinking.
#26
Sorry, guess I've ben not so clear again.
The main point that made me kinda worried was the
I'm not worried about the documentation of an alpha stage software. But, every coders knows that documentation should be written before or while coding - if you do it afterwards, chances are good that you'll document only the surface ("boy, do I really have to comment all that stuff now? I just coded 13 hours on that foo routine"). The normal exception is when you have a staff of tech writers that do the documentation.
So, there are no tech writers, and the coders don't document on the fly.
I know that td2 is alpha. But even in alpha stage all implemented functions should already be documented and in an ideal case those functions missing implementations should be stubbs that are documented as well.
Anyway, as soon as the intermediate release of t2d is released we'll know more. It's been over a month that we got asked if we want to see an intermediate release, so I guess we're going to see one soon - maybe even this year. And I'm really looking forward to it. The bugfixes alone are neat and all the added extras - yummy!
10/11/2005 (2:07 am)
Quote:@Lennart : I mean no disrespect, friend. From what I understand. T2d is still an early adopter product, right? When you do decide to buy it, it is clearly stated that you're getting basic docs and that's it. If it is not covered in the docs, simply start a forum topic. Well...you know how to do that, obviously :)
Sorry, guess I've ben not so clear again.
The main point that made me kinda worried was the
Quote:A) Charge 35 times the price of our products so that we could staff the 100+ tech writers needed to port all of that documentation to TDN in anything under a year.and
Quote:Finally, there are zero tech writers on staff at GarageGames.parts.
I'm not worried about the documentation of an alpha stage software. But, every coders knows that documentation should be written before or while coding - if you do it afterwards, chances are good that you'll document only the surface ("boy, do I really have to comment all that stuff now? I just coded 13 hours on that foo routine"). The normal exception is when you have a staff of tech writers that do the documentation.
So, there are no tech writers, and the coders don't document on the fly.
I know that td2 is alpha. But even in alpha stage all implemented functions should already be documented and in an ideal case those functions missing implementations should be stubbs that are documented as well.
Anyway, as soon as the intermediate release of t2d is released we'll know more. It's been over a month that we got asked if we want to see an intermediate release, so I guess we're going to see one soon - maybe even this year. And I'm really looking forward to it. The bugfixes alone are neat and all the added extras - yummy!
#27
Additionally, in an agile development software methodology you need to be careful about creating formal, end user targetted documentation (and I'm talking tutorials, etc. here, not source code documentation) during the development cycle--many times it's simply wasted effort as your source evolved through the cycles and iterations of the process of development.
BTW, your observation about "coders not coding on the fly" is actually not correct--as I mentioned earlier in the thread, there are roughly 300% more tutorials and documentation writeups for T2D in the next release (1.1).
None of this by the way has anything to do with the fact that moving all of the documentation that DOES exist already to TDN is an effort that requires assistance from the community, which was the point of my responses to Alex in the first place.
10/11/2005 (6:27 am)
@Lennart: the strategy you mentioned regarding when and how documentation is written (as well as the concept of "stubs"...ironically a term I haven't heard or even really seen used since my college days) is fine in theory if your project is a waterfall style methodology, but quite honestly not only is waterfall pretty out-dated, but in more than 30 software development projects over the last 10 years I have never seen a software development team that employeed a tech writer. At most, junior engineers or even interns were given the responsibility for documentation development.Additionally, in an agile development software methodology you need to be careful about creating formal, end user targetted documentation (and I'm talking tutorials, etc. here, not source code documentation) during the development cycle--many times it's simply wasted effort as your source evolved through the cycles and iterations of the process of development.
BTW, your observation about "coders not coding on the fly" is actually not correct--as I mentioned earlier in the thread, there are roughly 300% more tutorials and documentation writeups for T2D in the next release (1.1).
None of this by the way has anything to do with the fact that moving all of the documentation that DOES exist already to TDN is an effort that requires assistance from the community, which was the point of my responses to Alex in the first place.
#28
Of course, the less design / concept you have, the more often the methods will change - which will add the "overhead" of having to change the documentation as well. But that overhead is minimal in comparison to the gain.
Regarding code stubbs.. again, I don't see the connection to the waterfall method here. If you're creating a set of related functions, starting with the declararion is common, making it a code stub allows you to compile and test while working on it - but if you prefer to test everything later on, you can do that as well.
It doesn't change the fact taht doc'ing while coding is a pretty common and good idea.
Just because I'm curious: could you be so kind and show me the relationship between "doc'ing as you code" and "waterfall model"?
If you're referring to the "documentation should be written before or while coding" - I think it's a good idea to write the complete doxygen documenation block before I start coding the function - I am not saying that you should document every method before you start coding the first line.
If you got that impression, I apologize. As you said, that idea is so old that it never occured to me that someone would consider that an option.
Doc'ing while coding will provide this. It will also make the job for the tutorial writer more easy since he can either copy or link to the API docs.
10/11/2005 (6:56 am)
Um... sorry, but I'm sure that it's ok to add a couple of lines of doxygen comments to your public functions. And I don't see the connectioon between the waterfall modell and documentation.Of course, the less design / concept you have, the more often the methods will change - which will add the "overhead" of having to change the documentation as well. But that overhead is minimal in comparison to the gain.
Regarding code stubbs.. again, I don't see the connection to the waterfall method here. If you're creating a set of related functions, starting with the declararion is common, making it a code stub allows you to compile and test while working on it - but if you prefer to test everything later on, you can do that as well.
It doesn't change the fact taht doc'ing while coding is a pretty common and good idea.
Just because I'm curious: could you be so kind and show me the relationship between "doc'ing as you code" and "waterfall model"?
If you're referring to the "documentation should be written before or while coding" - I think it's a good idea to write the complete doxygen documenation block before I start coding the function - I am not saying that you should document every method before you start coding the first line.
If you got that impression, I apologize. As you said, that idea is so old that it never occured to me that someone would consider that an option.
Quote:Additionally, in an agile development software methodology you need to be careful about creating formal, end user targetted documentationAh. So no documenation is better than (too) technical documentation?
Quote: (and I'm talking tutorials, etc. here, not source code documentation)Well, in that case I fail to see the conenction to the code documentation, but anyway - besides the tutorials, you'll need a good API documentation.
Doc'ing while coding will provide this. It will also make the job for the tutorial writer more easy since he can either copy or link to the API docs.
Quote:BTW, your observation about "coders not coding on the fly" is actually not correct--as I mentioned earlier in the thread, there are roughly 300% more tutorials and documentation writeups for T2D in the next release (1.1).Sorry. Please understand that I can only refer to the version I have.
#29
You've kind of gone back and forth regarding what type of documentation you are frustrated with (and please, don't get me wrong--I'm not dogging your frustration at all...been there and done that with Torque myself), so I'll just lay out my personal beliefs here:
In the mid to late 80's the waterfall methodology was the only one that was taught. Basically, the concept taught was that yes, in fact, your documentation was written before you wrote a single line of (real) code, and that you stubbed out each and every function that would ever possibly exist in your code because you (theoretically) knew each and every thing that your code would ever possibly do. It sounded as if (to me at least) this was the idea you were discussing. Your latest response kind of suggests that you weren't.
Couple of response notes, since I just realized I'm getting late for the Boot Camp I have to go teach!
A) As has been mentioned in Ben Garney's .plan, the Elixer plug-in for TDN (where dOxygen formatted comments go directly to a database, which is then accessable by TDN) is due in next week. generation of the core docs from that won't take long, but setting up permissions will.
B) Yes, with an agile development methodology, writing docs (specifically tutorials, how-tos, and in-depth explanations of code) before the code has iterated over it's refactor cycles is IMO a waste of time. You don't want to wait -too- long obviously, but writing docs targetted for the end user before the code is even past the prototype stage is simply that: a waste of time. Your methodology requires the code to change (no one gets it perfectly the first time through, and you learn better ways as you iterate--fundamental core concept of agile software development), so why waste the time formally documenting something that is guaranteed to change, possibly fundamentally?
C) It comes down to a shifting definition of "doccing as you code". Originally this thread was about TDN, which is obviously not "doccing as you code". Should developers insert comments and use well described variable names, as well as strong coding practices? Absolutely. Should coders also use dOxygen format while laying out their classes and methods? I personally think so, but quite honestly it's difficult for engineers to be disciplined enough to do so. I personally know how important it is, but I've yet to get myself doing it either.
10/11/2005 (7:59 am)
I'm not particularly aware of your background, nor your relative "age" in regards to how software methodologies have developed over the last 30 years, so I can only go with how I've seen things change from when I was taught to what I see working now!You've kind of gone back and forth regarding what type of documentation you are frustrated with (and please, don't get me wrong--I'm not dogging your frustration at all...been there and done that with Torque myself), so I'll just lay out my personal beliefs here:
In the mid to late 80's the waterfall methodology was the only one that was taught. Basically, the concept taught was that yes, in fact, your documentation was written before you wrote a single line of (real) code, and that you stubbed out each and every function that would ever possibly exist in your code because you (theoretically) knew each and every thing that your code would ever possibly do. It sounded as if (to me at least) this was the idea you were discussing. Your latest response kind of suggests that you weren't.
Couple of response notes, since I just realized I'm getting late for the Boot Camp I have to go teach!
A) As has been mentioned in Ben Garney's .plan, the Elixer plug-in for TDN (where dOxygen formatted comments go directly to a database, which is then accessable by TDN) is due in next week. generation of the core docs from that won't take long, but setting up permissions will.
B) Yes, with an agile development methodology, writing docs (specifically tutorials, how-tos, and in-depth explanations of code) before the code has iterated over it's refactor cycles is IMO a waste of time. You don't want to wait -too- long obviously, but writing docs targetted for the end user before the code is even past the prototype stage is simply that: a waste of time. Your methodology requires the code to change (no one gets it perfectly the first time through, and you learn better ways as you iterate--fundamental core concept of agile software development), so why waste the time formally documenting something that is guaranteed to change, possibly fundamentally?
C) It comes down to a shifting definition of "doccing as you code". Originally this thread was about TDN, which is obviously not "doccing as you code". Should developers insert comments and use well described variable names, as well as strong coding practices? Absolutely. Should coders also use dOxygen format while laying out their classes and methods? I personally think so, but quite honestly it's difficult for engineers to be disciplined enough to do so. I personally know how important it is, but I've yet to get myself doing it either.
#30
Ok. You might have missed the fact that I'm talking about API documentation here.
Anyway, it seems like you have found a method that works for you - and if you think that it works well enough, there's no reason to change it.
10/11/2005 (9:27 am)
Thanks for the explanantion of the waterfall model. I'm not sure why you wrote it, but it's great that you took the time to do so.Quote:It sounded as if (to me at least) this was the idea you were discussing. Your latest response kind of suggests that you weren't.I apologize. I'll try to be more clear in the future. As I said, I never had the idea somebody would consider that an option in the first place.
Quote:Yes, with an agile development methodology, writing docs (specifically tutorials, how-tos, and in-depth explanations of code) before the code has iterated over it's refactor cycles is IMO a waste of time.
Ok. You might have missed the fact that I'm talking about API documentation here.
Quote:ut writing docs targetted for the end user before the code is even past the prototype stage is simply that: a waste of time.It isn't. If you write a function in a team, having it documented will save lots of time. It allows you to get into the code faster. Writing the documenatation while you code also helps you focus on the actual goal and helps finding flaws - it's kinda like a one person rubber-ducking cycle.
Quote:It comes down to a shifting definition of "doccing as you code". Originally this thread was about TDN, which is obviously not "doccing as you codeAgreed. It would simply make it more easy to maintain an uptodate documentation.
Anyway, it seems like you have found a method that works for you - and if you think that it works well enough, there's no reason to change it.
#31
I'll just add so that everyone's aware that immediately after ANY function is added to the codebase, I update the Open-Office document and output it's associated PDF file and then update that to SVN. The updates no matter what they are always get uploaded with the respective doco changes. If you had access to the SVN log, you'd see a description of "- Updated Doco" on almost every one of my updates.
If there are any changes that impact the tutorials, I also make them immediately. On top of this, I update the change-log document that is a filtered version of the subversion log.
I'm a real fanatic about not putting stuff off and sometimes it really slows things down but it's worth it in the end.
Having to generate a reference guide so early on was a pain and not something I'd normally recommend to anyone but it was a product release and needed one. It's been hard work maintaining it (as we expected) but now that things are really settling down, it's no biggy.
Also, all v1.1 T2D source-code headers use the dOxygen commenting syntax (and from now on will continue to do so) and we've also prepared a macro and a guide on how to setup and generate all the tools needed to get the doco out, including hierarchy graphs etc.
Hopefully, this'll give you a little more confidence about the doco. Obviously TDN is not about pure reference guides, it's about a whole host of other related material and keeping that current is a problem that's still got to be solved and I know there are already many suggestions.
With the release of v1.1, the codebase is going to change less and less now that it's really getting to the "maturity-point" so hopefully, syntactical and functional changes won't be a problem so much.
A little insider info; I've been sitting here in my computer room for the last three days writing tutorial documentation to go into the SDK and ultimately go into TDN. Doco is VERY important. We're not rewriting doco, we're just trying to catch-up with all the new features that we've finally finished.
The fact that people are hungry for doco means that people are using T2D which is all good. TDN won't have enough meat in it quick enough for some people but opening it up does allow people to see the direction GG is heading. Don't forget; nobody paid for TDN, you paid for a chunk of code with no warranty. Everything else is a bonus. That's not to say shut-up to everyone, heck TDN is saying that GG is LISTENING and ACTING.
I think everyone's confident that TDN will ultimately reduce the doco issues to something we can look back on and laugh at.
Hope this helps,
- Melv.
10/11/2005 (11:23 am)
Lennart said: Quote:I know that td2 is alpha. But even in alpha stage all implemented functions should already be documented and in an ideal case those functions missing implementations should be stubbs that are documented as well.
I'll just add so that everyone's aware that immediately after ANY function is added to the codebase, I update the Open-Office document and output it's associated PDF file and then update that to SVN. The updates no matter what they are always get uploaded with the respective doco changes. If you had access to the SVN log, you'd see a description of "- Updated Doco" on almost every one of my updates.
If there are any changes that impact the tutorials, I also make them immediately. On top of this, I update the change-log document that is a filtered version of the subversion log.
I'm a real fanatic about not putting stuff off and sometimes it really slows things down but it's worth it in the end.
Having to generate a reference guide so early on was a pain and not something I'd normally recommend to anyone but it was a product release and needed one. It's been hard work maintaining it (as we expected) but now that things are really settling down, it's no biggy.
Also, all v1.1 T2D source-code headers use the dOxygen commenting syntax (and from now on will continue to do so) and we've also prepared a macro and a guide on how to setup and generate all the tools needed to get the doco out, including hierarchy graphs etc.
Hopefully, this'll give you a little more confidence about the doco. Obviously TDN is not about pure reference guides, it's about a whole host of other related material and keeping that current is a problem that's still got to be solved and I know there are already many suggestions.
With the release of v1.1, the codebase is going to change less and less now that it's really getting to the "maturity-point" so hopefully, syntactical and functional changes won't be a problem so much.
A little insider info; I've been sitting here in my computer room for the last three days writing tutorial documentation to go into the SDK and ultimately go into TDN. Doco is VERY important. We're not rewriting doco, we're just trying to catch-up with all the new features that we've finally finished.
The fact that people are hungry for doco means that people are using T2D which is all good. TDN won't have enough meat in it quick enough for some people but opening it up does allow people to see the direction GG is heading. Don't forget; nobody paid for TDN, you paid for a chunk of code with no warranty. Everything else is a bonus. That's not to say shut-up to everyone, heck TDN is saying that GG is LISTENING and ACTING.
I think everyone's confident that TDN will ultimately reduce the doco issues to something we can look back on and laugh at.
Hope this helps,
- Melv.
#32
it makes me want to work with it more. Thank's.
10/11/2005 (11:56 am)
This helps a lot. I just got a look at the TDN Beta. The t2d section already has so much infoit makes me want to work with it more. Thank's.
#33
10/11/2005 (10:38 pm)
@Melv: Sounds great! Thanks!
Torque 3D Owner Matthew Langley
Torque
I think Tom Spilman said it best when I talked with him it at IGC (something along the lines of) "wiki's have a way over working themselves out." On top of that with such a great community as we have here, the docs will get posted, refined, and then polished, probably in that order too.