What you want in Documentation?
by Matthew Langley · in Torque Game Builder · 09/07/2007 (11:04 am) · 62 replies
I figured I'd post a thread about this to see if I can get some good feedback from people. The question is pretty simple:
What you want in Documentation?
I'm curious as to what different people want. This can include what is partially there but not completely, what isn't there and you think should be, or even what is there and you want more of?
One thing I will note is for the future we are shifting away from developing docs that step you through creating an entire game. We've found that these can be long and boring (since making an entire game has a lot of repetition and isn't exactly fun to learn with). It also means if the existing ones don't cover a game or content that interests you then you may avoid it completely, ex. If you don't want to make a fish game you'll avoid the fish tutorials.
We are going to focus more on concepts tied to application. Doing this will help reduce the size of the tutorial (make them more digestible) as well as hopefully teach you concepts you can piece together to make whatever you want.
Figured I would include at least that blurb before getting feedback.
Be honest, be brutal, but please be constructive if you choose to give feedback :)
Also please don't be too harsh about the past efforts as much as being constructive about what you would want. We've had limited resources to dedicate to TGB docs (lol me, and not even completely full-time on docs) so keep that in mind. I think we've done extremely well with limited resources. I feel launch and 1.1.3 was a great launch, engine wise as well as the quality and amount of docs. Especially considering before the current docs were released we really only had a single tutorial. I do think though our future efforts need to both step up the quality and quantity of the docs. The existing docs looked great compared to what we had before, but not much has been added (though maintaining alone is a huge task) during the past year (except some reference generation changes and framework updates, which have been extensive and time consuming, and allows us to more efficiently develop and maintain docs) so I think the current docs have become less appealing since they haven't grown.
This thread delivers no promises, though your feedback, input, and suggestions will be invaluable for future considerations.
What you want in Documentation?
I'm curious as to what different people want. This can include what is partially there but not completely, what isn't there and you think should be, or even what is there and you want more of?
One thing I will note is for the future we are shifting away from developing docs that step you through creating an entire game. We've found that these can be long and boring (since making an entire game has a lot of repetition and isn't exactly fun to learn with). It also means if the existing ones don't cover a game or content that interests you then you may avoid it completely, ex. If you don't want to make a fish game you'll avoid the fish tutorials.
We are going to focus more on concepts tied to application. Doing this will help reduce the size of the tutorial (make them more digestible) as well as hopefully teach you concepts you can piece together to make whatever you want.
Figured I would include at least that blurb before getting feedback.
Be honest, be brutal, but please be constructive if you choose to give feedback :)
Also please don't be too harsh about the past efforts as much as being constructive about what you would want. We've had limited resources to dedicate to TGB docs (lol me, and not even completely full-time on docs) so keep that in mind. I think we've done extremely well with limited resources. I feel launch and 1.1.3 was a great launch, engine wise as well as the quality and amount of docs. Especially considering before the current docs were released we really only had a single tutorial. I do think though our future efforts need to both step up the quality and quantity of the docs. The existing docs looked great compared to what we had before, but not much has been added (though maintaining alone is a huge task) during the past year (except some reference generation changes and framework updates, which have been extensive and time consuming, and allows us to more efficiently develop and maintain docs) so I think the current docs have become less appealing since they haven't grown.
This thread delivers no promises, though your feedback, input, and suggestions will be invaluable for future considerations.
About the author
Was a GG Associate and then joined GG in 2005. Lead tool dev for T2D and T3D. In 2011 joined mobile company ngmoco/DeNA and spent about 4 years working game and server tech. 2014 joined startup Merigo Games developing server technology.
#62
12/01/2007 (11:48 am)
Quote:Well I saw the newer documentation recently on the Torque X stuff and it looks like there is some movement in the right direction like the asking for feedback on a specific tutorial. That I do like to see.This is definitely the direction we're headed in the future. Whether or not something is well written and satisfying is a very subjective thing (especially if you are the author :) ), so we definitely want to move in the direction of getting more feedback from the people that are using the docs, and also more quantitative feedback that is easier for us to analyze and figure out where we're doing well and where we aren't.
Torque Owner Dan Maruschak