Home       About Me       Contact       Downloads       Part 75    Thinking   

Part 76: Documentation

January 10, 2013

I was thinking about the various unfinished pieces and loose ends of this project, and wondering if there was any point in finishing off my GUI code. The last time I worked on it was summer 2012, when it seemd that Shamus Young would use it in a project of his. Unfortunately, just as we were getting started, he got hit by lightning or something and turned into an author again. Nothing came of the work we did, and I got annoyed with the whole thing.

I've never contributed to any open source projects, and I have no idea how hard it is to get code used by other programmers. We're a pretty demanding bunch (myself included) and I know my style is very dated. Very few people have expressed any interest in the project code, and no one has built their own project with it, as far as I know.

Of course, since I don't finish these little projects, it's kind of hard for people to use the code. The other big barrier is lack of documentation. I was looking for a small project to get me started again, so I did something about that.

I've written a little ad-hoc parser to strip all the comments off the include files for my code and format them as web pages. I've also made sure that all the classes have at least a trivial comment describing them. Method descriptions are still mostly absent though.

I've added some introductory material, but it really needs a tutorial to be truly usable. If I end up doing more on the GUI, I'll put tutorial pages into the documentation.

The result is here: Documentation

Let me know what you think of the format. Improving the content would be a good project for those days when I'm not up to writing good code.

Project Direction

I still want to build a large world. I'm not thrilled with making the landscape entirely out of blocks, but I could live with it. Building with blocks still seems the way to go, since it's so much more accessible for non-artists (like me!)

I know what I want to build, I have most of the pieces, and could put together a reasonably complete plan at this point. It's just a matter of finding the energy and enthusiasm to do it. After all this time, I'm constantly wondering if there's any point.

My main frustration for the last year has been my health. It's been like having the flu for a year -- poor sleep, stomach problems, aches and pains. I've been unable to concentrate and have very little energy. If that's what it's going to be like for the next year, I'm not going to get much done. I should just do smaller projects, document them to death and hope someone else uses the code.

If I do start feeling better, I could finish the big project. My time is limited though, and I don't know whether to finish my various libraries. I originally thought that was the way to go, to give the project multiple ways to succeed. Even if the game was a flop, there would be a lot of useful pieces. Other people could use those, or I could rearrange it all into a new project.

It's probably obvious to you all by now that I'm kind of a perfectionist. I spent most of my career building tools, not applications. It's something I'm good at, and it's an easy pattern for me to fall into. And so I've spent a lot of time worrying about portability and performance. But when no one uses the code, it makes me feel the project is pointless.

As a tool builder, this large project frequently seems overwhelming. There's no way to do a perfectionist job on something so large! My only hope has been to make it open-ended (basically, a large tool) and let users finish it off with neat scenery, buildings, and games written in some scripting language.

If I am going to build the complete world, I suppose I should stop "dotting the i's" and just get on with it. I've been fussing around all year because it was easier when I felt bad to nibble around the edges than to do the hard parts of the project.

I'm still mulling all this over, and trying to improve my health. I haven't decided what to do.

This part needs a picture for hit counting, so here it is:

The office I built into my van, when I lived in Santa Cruz. I did a lot of programming there!

Home       About Me       Contact       Downloads       Part 75    Thinking   

blog comments powered by Disqus