Documentation is tough work...
by Michael Perry · in Torque Game Engine · 05/14/2007 (10:48 am) · 18 replies
Man. . .I thought programming was hard! The first part of the tutorial series was only 9 pages, the second grew to about 26 pages, and the third (to be released in a day or so) will easily reach 80 or 90 pages. Phew!
Since the collaboration between my self and Edward Johnson is still in the early stages (with only a couple of tutorials and FAQs having been released), I thought I'd take the time to ask the community for help.
No, I'm not asking you to write docs too (don't let me stop you, though (= ). I was hoping to get some feedback on what tutorial formats seem to be the most helpful or popular.
If you want to cite already available documentation, just post the link.
If you have comments or criticism about the format of our current tutorials and documentation, feel free to let us know.
Then there are just the trivial things, such as file formatting: Preference of .doc formatting or .pdf?
Feel free to just babble on about color code syntax, picture usage, appendix recommendations, or just post what you feel you would like to see in the new tutorials/documentation.
As always, any help is greatly appreciated and your comments are more than welcome.
(see my profile for the .plans containing links to the tutorials written so far)
Since the collaboration between my self and Edward Johnson is still in the early stages (with only a couple of tutorials and FAQs having been released), I thought I'd take the time to ask the community for help.
No, I'm not asking you to write docs too (don't let me stop you, though (= ). I was hoping to get some feedback on what tutorial formats seem to be the most helpful or popular.
If you want to cite already available documentation, just post the link.
If you have comments or criticism about the format of our current tutorials and documentation, feel free to let us know.
Then there are just the trivial things, such as file formatting: Preference of .doc formatting or .pdf?
Feel free to just babble on about color code syntax, picture usage, appendix recommendations, or just post what you feel you would like to see in the new tutorials/documentation.
As always, any help is greatly appreciated and your comments are more than welcome.
(see my profile for the .plans containing links to the tutorials written so far)
About the author
Programmer.
#2
I tend to favor html for writing docs since it can translate easily to the web (obviously =P), it makes it easy to update the images later if you find an error (without having to reupload the whole doc), it is fully cross-platform with a *ton* of different ways to read things, it has nice text positional tools built in (which aren't always as cross-platform as I'd like), and it translates to TDN and GG resources easily. Also since it is a text based format it can be fairly easy to have automated tools pull out a Table of Contents or an Index as well as create crosslinks between related portions of the document. It really doesn't take very much html knowledge to write tutorials.
You should drop me an email. There are some cool things coming!
05/14/2007 (2:18 pm)
PDF's can be good but these days Acrobat Reader is quite the resource hog. It can also be hard to read longer PDF's on certain monitors/resolutions (on widescreen resolutions on my laptop Fit-to-Page makes the text too small while Fit-to-Width makes for a *ton* of scrolling...especially in a two column document).I tend to favor html for writing docs since it can translate easily to the web (obviously =P), it makes it easy to update the images later if you find an error (without having to reupload the whole doc), it is fully cross-platform with a *ton* of different ways to read things, it has nice text positional tools built in (which aren't always as cross-platform as I'd like), and it translates to TDN and GG resources easily. Also since it is a text based format it can be fairly easy to have automated tools pull out a Table of Contents or an Index as well as create crosslinks between related portions of the document. It really doesn't take very much html knowledge to write tutorials.
You should drop me an email. There are some cool things coming!
#3
05/14/2007 (2:26 pm)
I would think you'd use Docbook http://www.docbook.org/ as it is easily converted to any format you want. 
#4
I also prefer html, all TGB docs are done in html now with a framework that parses them for some of the things Matt F. was talking about. HTML is easy to scan to index, generate a Table of Contents, and various other aspects. Plus it isn't too hefty and loads quickly in a web browser.
05/14/2007 (2:32 pm)
You're right, documentation is very hard work =/ You realize this once you start making massive tutorials that just grow and grow before you know it. You really learn how hard it is when you try and make small tutorials that accomplish big goals. Making a helpful tutorial fit into small space is one of the most useful things to people (since people tend to lose attention span and/or don't want to complete numerous massive tutorials) and it is one of the most challenging documentation.I also prefer html, all TGB docs are done in html now with a framework that parses them for some of the things Matt F. was talking about. HTML is easy to scan to index, generate a Table of Contents, and various other aspects. Plus it isn't too hefty and loads quickly in a web browser.
#6
I was getting concerned with the size of my third tutorial, and how I was going to organize the 300+ pages of unorganized notes and documents. I think breaking it all down to mini-tutorials, the size of my second tutorial, with appendices used as a reference for engine/script function would work perfectly with an html format similar to what is found in the TGB documentation.
Keep the suggestions coming, and e-mail coming your way Matt (Fairfax).
05/14/2007 (4:05 pm)
Thanks for the input so far everyone. I definitely want to convert to the files I'm uploading (currently in .doc format) to html, though I have no experience in doing so. Of course, from what I remember during the 1 hour lab I took at Full Sail covering html, it probably wouldn't be too hard.I was getting concerned with the size of my third tutorial, and how I was going to organize the 300+ pages of unorganized notes and documents. I think breaking it all down to mini-tutorials, the size of my second tutorial, with appendices used as a reference for engine/script function would work perfectly with an html format similar to what is found in the TGB documentation.
Keep the suggestions coming, and e-mail coming your way Matt (Fairfax).
#7
One is it's fine *if* you can d/l the entire set of resources then read at you're leisure when you're not hooked to the net. Also, fine as long as the hosting service is working correctly when you must refresh your memory on a certain tut if you haven't d/l'd it.
Second and similar to the above is searches. You really cant easily search an offline html set of pages without some alternative tool and in many a tutorial you can't search them online either.
The last thing, and this one is a real big one, is formatting. I'm really not sure how savvy word is these days, but in the past, writing and formatting all your docs in word then trying to export it to html was little more then a nightmare. Also, you're fairly restricted on font faces, image placement and you should plan ahead for printing. All of this can be easily taken care of with expensive programs like dreamweaver, thats if you know how to use it:) BBEdit is a cheaper option if you know enough html.
You're right about acrobat becoming a resource hog, but firefox running right now is 30 MB's and I've only opened a couple links ;) Launching the pdf extension only adds about 10 MB on to that. Not trying to discourage you from posting a tutorial on the web or even in html, but pdfs have some interesting advantages as well, especially when it comes to file sizes.
I always like the tutorials on the web that included a nice little pdf to d/l too! Those are my favorite :)
05/14/2007 (4:10 pm)
Couple things i really don't like about html.One is it's fine *if* you can d/l the entire set of resources then read at you're leisure when you're not hooked to the net. Also, fine as long as the hosting service is working correctly when you must refresh your memory on a certain tut if you haven't d/l'd it.
Second and similar to the above is searches. You really cant easily search an offline html set of pages without some alternative tool and in many a tutorial you can't search them online either.
The last thing, and this one is a real big one, is formatting. I'm really not sure how savvy word is these days, but in the past, writing and formatting all your docs in word then trying to export it to html was little more then a nightmare. Also, you're fairly restricted on font faces, image placement and you should plan ahead for printing. All of this can be easily taken care of with expensive programs like dreamweaver, thats if you know how to use it:) BBEdit is a cheaper option if you know enough html.
You're right about acrobat becoming a resource hog, but firefox running right now is 30 MB's and I've only opened a couple links ;) Launching the pdf extension only adds about 10 MB on to that. Not trying to discourage you from posting a tutorial on the web or even in html, but pdfs have some interesting advantages as well, especially when it comes to file sizes.
I always like the tutorials on the web that included a nice little pdf to d/l too! Those are my favorite :)
#8
I love using LyX. You don't have to think about formatting, /at all/. It takes a while for the koolaid to sink in [do the tutorial], but once you get it, it's great. You just focus on the content&structure and it does all the layout for you.
LyX actually uses LaTeX for stuff in the "back end", so you can output PDF, postscript, plain text, HTML, docbook, rtf, any of a number of things.
It does understand images, math, masses of other stuff. All the complaints about the UI [there's a lot, and they're almost all valid] in 1.4 will be mitigated once 1.5 becomes stable.
Gary (-;
05/14/2007 (4:28 pm)
LyXI love using LyX. You don't have to think about formatting, /at all/. It takes a while for the koolaid to sink in [do the tutorial], but once you get it, it's great. You just focus on the content&structure and it does all the layout for you.
LyX actually uses LaTeX for stuff in the "back end", so you can output PDF, postscript, plain text, HTML, docbook, rtf, any of a number of things.
It does understand images, math, masses of other stuff. All the complaints about the UI [there's a lot, and they're almost all valid] in 1.4 will be mitigated once 1.5 becomes stable.
Gary (-;
#9
Being able to select a section, click "up", and see that section move up in your docs, and have all cross references etc update themselves is beyond awesome for me.
I've never found an HTML editor that did stuff friendly to writing documentation.
Gary (-;
05/14/2007 (4:30 pm)
IME, the secret to writing docs is finding the tools to do it, rather than worrying about the input format. My personal experience is that word/openoffice are just miserable POS's if you want to write nontrivial volumes of text.Being able to select a section, click "up", and see that section move up in your docs, and have all cross references etc update themselves is beyond awesome for me.
I've never found an HTML editor that did stuff friendly to writing documentation.
Gary (-;
#10
Completely agreed... also the Open Office html converter is an exceptional POS. When we mitigated the TGB docs from OpenOffice (we used PDF Factory to export PDFs from Open Office) to html (when I started developer our doc framework) the html format it spit out was beyond bad. Also Open Office is great for quick and small docs, though it is very clunky when working with lots of docs.
Agreed... Thats why I ended up developing a Doc Framework, Generator, and HTML tool for GG docs. The way I have it set up you simply place the doc wherever you want it and the rest is handled (ToC, search table parsing, etc).
05/14/2007 (4:38 pm)
Quote:IME, the secret to writing docs is finding the tools to do it, rather than worrying about the input format. My personal experience is that word/openoffice are just miserable POS's if you want to write nontrivial volumes of text.
Completely agreed... also the Open Office html converter is an exceptional POS. When we mitigated the TGB docs from OpenOffice (we used PDF Factory to export PDFs from Open Office) to html (when I started developer our doc framework) the html format it spit out was beyond bad. Also Open Office is great for quick and small docs, though it is very clunky when working with lots of docs.
Quote:Being able to select a section, click "up", and see that section move up in your docs, and have all cross references etc update themselves is beyond awesome for me.
I've never found an HTML editor that did stuff friendly to writing documentation.
Agreed... Thats why I ended up developing a Doc Framework, Generator, and HTML tool for GG docs. The way I have it set up you simply place the doc wherever you want it and the rest is handled (ToC, search table parsing, etc).
#12
Ok, while the final decision hasn't been made, I think I'll offer each tutorial in 2 (maybe 3) formats for download. Since I'm already writing them in .doc/.sxw format, that will be one format. I'll take a stab at converting to an html format, and I'll see how the conversion to PDF goes and make that a possible 3rd format. This weekend, after I post the 3rd tutorial, I'll take a stab at a few conversion processes and applications to see what kind of time-hit I get.
Keep 'em coming people, this is good stuff so far =)
05/15/2007 (5:34 am)
I'd be very appreciative to have that template, Berserk, just in case. Thanks.Ok, while the final decision hasn't been made, I think I'll offer each tutorial in 2 (maybe 3) formats for download. Since I'm already writing them in .doc/.sxw format, that will be one format. I'll take a stab at converting to an html format, and I'll see how the conversion to PDF goes and make that a possible 3rd format. This weekend, after I post the 3rd tutorial, I'll take a stab at a few conversion processes and applications to see what kind of time-hit I get.
Keep 'em coming people, this is good stuff so far =)
#13
05/16/2007 (8:27 am)
E-mail sent, Matt (Fairfax).
#15
Yes, that Matt F. and this Matt F. are the same guy. I would have suggested looking at www.rustycode.com, but a quick check shows a lot of dead links on that site.
05/19/2007 (12:11 pm)
Hi Berserk,Yes, that Matt F. and this Matt F. are the same guy. I would have suggested looking at www.rustycode.com, but a quick check shows a lot of dead links on that site.
Torque Owner Jason Lee
About format, I really think many people have varied ideas on what works best for them, so as the writer you're pretty much stuck with what makes the best sense to you. Basically sticking with chronological order from beginner to advanced methods more then likely works the best with some decent picts of the process. Did i mention i love pdfs with hyperlinks? oh yeah well....