Engineered learning

When it comes to making tutorials, there are key aspects that need to be fleshed out before you dive in and make it - aesthetics, content, structure, and one that is overlooked by many, conciseness. Conciseness is a huge problem with many tutorials I've read, and its one that many could avoid by following a few simple steps:

1. Use diagrams more often. Understanding concepts such as prefix trees and mesh networks with only text can be a painful process for people with no experience in the subject. A diagram gives the reader a visual way of interpreting the information. Most importantly, diagrams let you show how something works, rather than explaining it. This in turn lets you explain less about the concept at hand and let the person absorb the information visually.
   
2. Use screenshots. They say a picture is worth a 1,000 words, but those people obviously haven't seen some of the obnoxious photos people post of themselves on Facebook that only say "Look at me, I'm an idiot!" When writing a tutorial, the images will be professional and have a point, or else you're wasting your time even collecting said images. For example, if the person must insert some information into some dialog box in a GUI, rather than telling them what to insert with a step by step process, show them a screenshot of the GUI filled out with the correct data. If you're explaining how to do something in a videogame, show a screenshot of it being done in-game.
3. Get to the point. You might be surprised at how perceptive people are at understanding concepts explained in short - if you really think that the user needs to know the details of something, have some sort of information bar on the side or some dictionary containing a more detailed description of the concept. It's easy to get lost in a wall of text. Spread it around. This will let you get to the point. Don't ever be afraid to cut out large chunks of text - it may improve the tutorial drastically.
   

As well, good structure is key to a successful tutorial. You need to have either prerequisites or at least cover the concepts that the user of the tutorial must know to move forward, if there are any. Never talk about something without being extra confident that the reader is prepared to hear about it. You must walk before you can run, and you can't expect someone who lacks the skills or knowledge to complete your tutorials to actually accomplish anything with them. Also, make sure you cover relevant information, and nothing else. If there is something that the reader might want to check out, link them to where they can get information. Don't confuse the reader by jumping around topics.

The content of each tutorial has to be useful, too, and it has to be easy for the person to understand, so content and structure are very dependent on each other. Include examples or analogies in your tutorial, so the user can relate what you're talking about with something they may already have knowledge about or experience with. If its a programming tutorial, show some code examples of how to use the API or framework or language. Examples are great - do not be afraid to use them liberally no matter the subject.

Aesthetics are also very important, and I would argue just as important as the other key parts of a tutorial as they tie right in with the structure and how you will lay out the tutorial. Man pages worked nice for showing a user examples of how to use Unix commands and what to do with them, but many of our goals and projects have become larger and require better ways of structuring the information, and straight text is just not going to cut it in most cases. Have areas where you can put less relevant information, and if the user wants to check it out, they can. Format your text. The user should know what they're looking at based on how the text looks. If you're writing a programming tutorial, have code blocks with courier font or any other fixed-size font.

Don't worry, the irony of writing what could be considered a recursive tutorial is not lost on me.

The "Experience"

As this project has progressed, our overall goal has become clearer - this "out-of-the-box" experience is not some tech demo, nor is it some cool game that people can play and say "This is really awesome." Our project is simply a quick introduction to Project Darkstar, how the technologies help developers, and what it can be put to work on, namely powering the server side of massively-multiplayer games. Having a user create a full fledged massively-multiplayer game is way out of the scope of this tutorial - many large companies take a crack at it and find themselves failing epicly while trying to make one. So we have to scale the scope of the OOTBE to be compact, quick, and informative. Fortunately, there is this great open-source project at Sun called Project Snowman that is exactly what we're looking for - its a 3rd person capture-the-flag style shooter where players fight each other as snowmen on a snowy tundra. Fortunately, the code base is pretty solid - with a little bit of digging I was able to find where Entity updates were handled, how messages were parsed, and how players communicated with each other, among other things. By "tutorializing" Project Snowman, hopefully we can give developers a fun and information introduction to the Project Darkstar technologies so that they can go ahead and use Project Darkstar on their own personal endeavors.

While I did mention Project Snowman last week, we were not exactly sure if we were going to use it. We were told that the code was not good - from the looks of it, the only thing lacking is great documentation. The code itself is written in a fine manner, and while it might be good to tweak it, its not so bad that we will be spending our time doing that, since there are far more important matters at hand. The key thing here is that developers have a good first experience with Project Darkstar - first impressions are lasting impressions, and if we want to get more people using it then they have to have a good first impression of the technology. We believe that we can achieve this goal, but it's not going to be easy.

"Speaking Points"

The subject of this blog is about this thing called "Speaking Points," and in particular, speaking points in relation to Project Darkstar. So far, we've spent most of our time researching and learning, but we've also done our fair share of production in the past week and a half. So far, we've nailed down our out-of-the-box experience to be a culmination of 3 things: An installer, a game/game-framework, and a series of tutorials.

The idea of an installer was not obvious to us from the start. When we first made our way to Sun, we were expecting to sit down, load up Darkstar, and immediately crank out the greatest game framework in 7 weeks with the most in-depth tutorials possible. However, in life, the devil is in the details, and the details of how to get Darkstar up and running were not easy to track down. Our first experience with Darkstar was that it was cumbersome to use and information on how to intially get it up and running was either outdated or nonexistant. Fortunately, we work with the guys who are making it, and their expertise was invaluable to learning how to set it up initially. As well, we were able to track down some minor issues with the loading process that only affect a small number of PCs, but in the end we were able to understand how to use the system. Still, for a newcomer, it wouldn't be surprising for them to turn away based on how intimidating it may be. In reality, its not bad at all. But, for us to say that this was a successful OOBE, every second has to be streamlined. So, our team came up with the idea of an installer, which the Darkstar team was all for. In the end, there will be both a GUI and shell version of the installer. What Chris ended up doing was writing a front-end installer framework, and what I've done is written an installer back-end framework. The goal is that making changes to the backend will only require a minor update in both front-ends, so the change is reflected in both views. Fortunately, most of the that is complete. I predict about another day and a half of work to get both the GUI installer and shell installer complete. We still have to write test-cases though - those might be tricky in our system, since there is a lot of file movement, and simulating that can be difficult unless properly done.

The two other parts of the project are the actual game as well as tutorials that go along with the game. I will touch upon those in my next blog post.

Project Wonderland and Sun Spots

Yesterday, I was able to watch a wonderful presentation about Project Wonderland, a project which I think has a bright future and has some extremely interesting features. I did not write about it while watching the presentation since I was admittedly captivated and wanted to absorb as much as I could about the technology - it was definitely something I could see myself using down the road.

Project Wonderland is a framework for developing online worlds - and Sun is doing some really neat stuff with it. One of the big features in the release I was shown was the use of sound. In the game, sound is sent out radially to simulate how sound works in the real world, and as well there are 'cones of silence' where only users within the cone of silence can hear the sound. As well, they have a neat "cell" system where people can easily create their own sections of the world, as well as things in the world.

Today, we were also given a pair of Sun Spots to play around. These things have a really awesome out-of-the-box experience, in which the default program loaded onto them is a bouncing ball demo, that can communicate with any other Sun Spots it detects and bounce its ball over to them. It has to be seen to be understood, but its pretty damn impressive. Also, fooling around with the Sun Spot is pretty trivial - you load a program to communicate with it, write your program, and in your Sun Spots NetBeans project, right click and tell it to deploy. Very cool.

My First Day

As my first post in regards to my Sun Microsystems MQP, I'll state my reasons for having this:

• Keep track of what I've done
  
• Keep track of what needs to be done.
• Give updates as to the status of the Darkstar project and what I'm doing.
• Write about things I discover about Darkstar that someone might find useful.
  

My group consists of my friends Chris Scalabrini and Rob Martin and myself. We're in the process of trying to figure out some cool "out-of-the-box" experience to make for Darkstar. For research purposes, Rob and Chris are forcing me to play World of Warcraft, Dark Age of Camelot, and other MMO games. Normally, I would not touch these games (and so far I've found WoW to be as boring as I imagined) but I need to learn more about MMOs so I can start coming up with ideas of how to take MMOs to the next level. I have some ideas I'm planning on developing in the future, but I need an idea that can be implemented in 7 weeks.

The tasks assigned to me today are the following:

• Measure success - what are the problems I'm trying to solve, and how am I going about it.
• Write documentation! I will have to develop a report and presentation for the team and myself.
  
  • Team Documentation - we have to work together to get this done.
  • Personal Documentation - write about what I've been working on.
• Gather references.
• Write weekly goals, and meet them.
  
• Research!

Fortunately, my team kicks ass so meeting these goals should be mostly going through the motions. We're all really bright guys so our biggest challenge is going to be setting realistic goals to ourselves, as well as goals that make the guys we're working with happy. I'm actually looking forward to pitching my project, since I'm sure that whatever we come up with will be both interesting and cool, and this will be the place to go to keep track of any of the cool things that happen.