Writing an SCI Tutorial : Ideas

[Nostalgic]

This may sound like a silly question in one sense. Here's the context: let's say you have someone writing a tutorial for SCI. Here's the question:

Would you recommend the tutorial focus on SCI Studio or SCI Companion? Or should the tutorial cover both in equal detail?


Beyond that issue, basically I'm trying to write up a moderately decent tutorial as part of a "nostalgic" tribute to game systems from the past. Part of this, of course, is a necessary focus on the tools used to create such games. What I'm hoping to do is not totally re-invent the wheel in all cases. For example, I'm using bits and pieces of tutorials I've already found. But I'm putting them in a wider and more cohesive context that tries to actually explain how SCI works.

If anyone has any ideas about what such a tutorial should include or focus on, I'm happy to hear about it.

Just two examples of what I'd like to include:

Build Sample Game (or Parts Thereof):
I'm trying to contact the original author of the LockerGnome game (listed on the SCI Studio site). I would actually like to use that (or some other open sourced game) as part of the tutorial, in terms of building up that game (or some part of it) as part of the tutorial. I often find this an effective way to present game tutorials, by taking an existing game that people can see and play with and then showing them how to build it. Or a part of it. Another example is "Knight's Quest" and the scene in the jail.

Scripted Scenes:
I'd like to include something about how to build "cut scenes" -- essentially automatic sequences where everything that the characters are doing is scripted. (Again, "Knight's Quest" has a large part of this at the beginning.)

[Doan Sephim]

I would probably focus on SCI Companion as it is the program I would suggest people begin with. The coding will be the same on either, so it would be valuable for people who use either or both...but I think the SCI Companion is the one to focus on. The guy who made (Troflip) it is around to answer questions and address bugs and it has more functionality to it.

I don't think the creator of LockerGnome quest will get back to you. He has moved in a different programing direction and doesn't respond to emails about SCI.

Thanks for your work!

[Nostalgic]

I would probably focus on SCI Companion as it is the program I would suggest people begin with. The coding will be the same on either, so it would be valuable for people who use either or both...but I think the SCI Companion is the one to focus on.

That makes sense and is the direction I was leaning in.  I actually find SCI Companion a more useful program than SCI Studio in a lot of ways.

I don't think the creator of LockerGnome quest will get back to you. He has moved in a different programing direction and doesn't respond to emails about SCI.

Yeah, it's been awhile and no response, so I think I'm out of luck. I could just craft my own game I suppose and that probably would be the intellectually honest thing to do. The problem is that part of me writing the tutorial is also how I'm learning SCI, so there's a bit of a chicken and egg thing there.

What I started doing is building off of the existing SCI Tutorial (on the SCI Studio site) but rewriting large portions of it, adding more examples, and clarfiying what I had found to be confusing aspects. That's how I came across LockerGnome in the first place.

That said, part of what I'm doing is crafting some of my own rooms as well. So it's not like everything I'm doing is totally stealing. (That sounds suspiciously like a feeble rationalization, doesn't it?)

Nothing I'm going to present is going to be terribly new, I feel, but my hope is that it will be in a wider context; a sort of distillation of various topics that have come up. It would be nice to reduce any entry barriers for people who want to learn SCI. I'm thinking something that's a cross between a tutorial and a reference.

[troflip]

Yes, of course you should use SCI Companion 

I'm also still working on making it support a c-style syntax instead (or rather, in addition to) the LISPy syntax.  I don't know if that would affect your tutorials or not... it isn't ready yet (haven't had much time to work on it lately), so it couldn't be incorporated into tutorials now anyway.  One task I don't look forward to is having to substitute all the code in the tutorials with new c-style code.  Maybe somehow you could write your tutorials such that this was easy to do.

Also, don't know if it's relevant.  But I was planning to have class/method documentation automatically generated from specially-marked-up comments in the code.  I've already added functionality (not in any released version yet) to extract this information from comments and turn it into an object model from which it won't be hard to auto-generate html pages from it.  However, I haven't actually gone and added the function/class descriptions to the comments yet (that's a lot of work).  So if you end up writing any documentation like that, I would be interested in using it.

[Nostalgic]

I'm also still working on making it support a c-style syntax instead (or rather, in addition to) the LISPy syntax.  I don't know if that would affect your tutorials or not...

As long as the C-style is in addition to the LISP-like syntax, as you mention, this may not be too much of a problem. I had written a tutorial about using Java and Junit and then I started using that same tutorial to write about using C# and Nunit. What I ended up doing was abstracting the common bits and then getting specific for each particular language/tool.

I could probably do something similar for the idea of the LISP-like vs. C-like programming style for SCI. I could see two ways of doing it.

(1) Just have the scripting sections be broken into two literal sections. One that covers the LISP, the other that covers the C.

(2) Interleave the LISP and C examples as part of one section, but indicate to the reader that they are going to be picking one or the other.

Also, don't know if it's relevant.  But I was planning to have class/method documentation automatically generated from specially-marked-up comments in the code.

So this is sort of like the javadoc comments in Java or the XML summary comments in .NET?

That's an interesting (and good) idea. Let me see how far I can get in something like that. I'm still learning the in's and out's of SCI but a good way for me to learn that would certainly be to go through and put in function/class descriptions. My main concern would be my accuracy at this point.

[troflip]

Yes, it will be very similar to javadocs...