3D Programming - Weekly : Writing Tutorials

This is an article about writing articles. I must be running out of topics. Many of my suggestions here are probably things I don't do, but would if I had time.

On Writing

Since I know of a lot of ways I could improve my own articles, I'm often tempted to insert apologies into the articles themselves. This doesn't seem to be limited to me, I've seen them in quite a few tutorials by other people. I try not to do it in the interest of brevity. I see my articles as informal thoughts rather than the final word on anything. Maybe when I stop writing new weekly articles, I'll go back over them and the full tutorials and improve them.

Speaking of brevity, when I read over a first draft, I remove non-essential parts, either words within a sentence, or even entire sentences. In school I'd sometimes do just the opposite to meet minimum length requirements, since I was writing about assigned subjects I didn't have much to say about. I'm not sure why I still got good grades on my papers. The padding definitely made them worse.

One thing that conflicts with brevity and directness is telling a story. This can be a good idea to avoid being too dry, or sounding like a robot. I actually try to do both, but I lean more towards technical than entertaining.

Remember to organize your article into smaller sections and make a table of contents. For some reason I didn't think to do this with the first tutorials I wrote, even though it doesn't take long.

Diagrams & Images

Good diagrams are an important part of a tutorial, one that I've mostly neglected recently. They can be drawn to illustrate a point, or screenshot based like the example here.

vector interpolation This diagram from my Object Space Normal Mapping Tutorial shows how linear interpolation of unit vectors results in them becoming unnormalized, specifically shorter than unit length. The diagram is 2D, but the same holds true for 3D, or higher dimensions. It's not a complicated diagram: The unit length interpolation curve is just part of a circle, the linear interpolation is a straight line. I was proud of this diagram, maybe because it was one of my first diagrams.

There are some diagrams I'm a bit jealous of. For example, on the Wikipedia page for bezier curves there are animated gifs tracing the curve from t=0 to t=1 (under Constructing Bézier curves.) They are impressive looking, and useful =)

Sample Code

Since most of my tutorials are ultimately about writing code, sample code is an important part of it. I like to put any sample code in code boxes with color coding for comments, keywords, etc. I wrote a php script to automatically do the color coding.

I'll freely admit that I'm more lax than I'd like to be about testing my code snippets. It's all stuff I've coded before though, and I refer to working code, so I hope it's all at least mostly correct. A problem with snippets is fitting them in with other code, especially since in 3D programming there are lots of things that could be slightly different (signs, direction of rotation, order, as well as everything that will be different for different hardware and APIs.) I have heard complaints about the code in many books on programming though, and authors get paid for those books, so I don't feel as bad as I might otherwise.

Sample Programs

I'm pretty good at learning from examples. For example, I can check the code to see if there's anything missing in my own code. Also very helpful in understanding new ideas is the ability to make incremental changes in working code and see if it affects the output the way I think it will. Once I understand it, I can write my own.

This is one reason why artists often suggest drawing from life instead of photographs. If you draw from life, you can change the lighting yourself, and see the effects on shadows and highlights and the bounce light, or change the positions of objects and see how the lighting, or folds, or anything else, is affected. Then you can use what you learn when you draw without reference.

Why don't I have much for sample programs with my tutorials? It's mainly because I prefer to spend my programming time on other programs. Unless you're writing about simple stuff, sample programs probably take the longer than any article. I think creating an open-source program, and using it as the basis for tutorials is an interesting idea. I might try it someday.

Feedback

Overall I haven't tried to get much feedback. I am surprised that of the people who've emailed me about 3d programming, there's an approximately 100% sanity level. (This is the internet, can you blame me for being worried?) People have expressed their appreciation. Some asked programming questions. A few people have pointed out obvious errors in tutorials, which I've then corrected.

Community building is now considered just about a must for having a popular website. I've had a couple people suggest I add comments to my blog. Comments and forums are in fact something I'd suggest to anyone serious about increasing readership/visits. This webpage has always been secondary to me to actually programming though, so I've avoided anything that would require I spend more time on it.