Shawn Hargreaves Blog
Dear Reader, I have another question for you...
I sometimes notice people using samples from creators.xna.com, having trouble with them, but not realizing their problem is answered in the sample doc.
The first time this happened, I could dismiss it as just a stupid user. But I have seen it too often for that to be the case.
All our samples include a document. The quality varies from minimal to pretty darn good indeed, but there is always something, and in a few cases the document is even more important than the sample code itself.
Have you used our samples? If so, it would be great if you could help me understand how this worked out for you:
On an unrelated note, Neal Stephenson has a new book out!
Funny you mention it. I recently downloaded the "Tiled Sprites" sample, and while I thought it was quite helpful I didn't even notice that it had documentation until your post stating that they *all* had documentation. In retrospect, I'm not sure why exactly it didn't notice it the first time around -- it resides in the same location as the .sln file. Some other things that may (or may not) work:
-I've been accustomed to code samples that included a "Readme" file. Perhaps instead of giving the documentation the same name as the project name, it would stand out a bit more if you just called it "readme.htm". Of course, the downside is that you'll have name collisions if users are extracting these samples to the same location.
-(disclaimer: I don't even know if this is possible) Since Visual Studio "remembers" the open documents from a previous session, can you configure the .sln file in such a way that the .htm docs are already opened when you open the solution?
-Include a brief mention the documentation in the inline comments? That way if people jump straight to the code they'll learn that it exists.
I think the second of your suggestions actually happen for some samples, but people still don't read it.
I always take a quick look at the documentation (I got used to the fact that it's there), but a new used just doesn't spot them.
I think that maybe adding a link to the documentation, clearly labeled as such in the download page for each sample would help.
I have read the docs with some of the samples, but most samples have enough comments in the code for me to follow.
It's not just stupid users, it's laziness. The majority of the questions on the forums can be answered with about 5 minutes of Googling or reading the help file with GS. That's too much effort for most people though. :(
Can you add the document to the solution and just give it a "do not compile" setting?
> It's not just stupid users, it's laziness. The majority of the questions on the forums can be answered with about 5 minutes of Googling or reading the help file with GS. That's too much effort for most people though. :(
Machaira: that could make sense, except that ZMan was one of the people who didn't notice the sample docs :-) If the faq-maker-extraordinaire fails to find something, I think we have a problem!
> Can you add the document to the solution and just give it a "do not compile" setting?
I like this option.
I myself have used the examples extensively (Thanks a TON for providing them). I've always been cognizant of the documentation but haven't really looked at it. Though I probably should have on the Matrix math in the Transformed Pixel collision (Multiplied my matrices out of order!). For the most part though, the code has been self explanitory and/or well commented.
When you posted that I thought "duh, how obvious, why haven't we been doing this all along?"
But then I tried it :-) Unfortunately it seems like when you add a document to VS, it opens it in the VS text editor, rather than in an external document viewer. I tried this with both HTML and RTF documents, and in both cases VS just shows the underlying text source when you open the readme. I can't find any way to change that.
I think the issue also might be related to the quality/helpfulness of the document. I am currently working with the Game State Management sample, and the document, for someone like me, is not very complete. I am having to just read the code and the comments to understand how everything works.
That being said, I think the best possible thing would be to have a video-tutorial going over each bit of the code, explaining as you go how things work. This could replace the video already present on each sample's page. That video, today, only shows the end result.
I assume the document is the .html file that comes with the same name as the sample where the Multipasslighting sample contains a file MulitpassLighting.html. I have noticed and used these, but they might stand out as documentation if they explicitly were labled as such,e.g.,
I find that most the users who are asking questions that are clearly stated in the documentation are the same users asking about what xna book they should buy. Honestly, I should just print out the docs and start selling them as a new XNA 3.0 book...
I especially enjoyed "Snow Crash"
When looking at some samples in the CTP I also didn't spot that there were accompanying HTML documents. I would expect such documents to be part of the solution, maybe under a Documentation folder. I don't think it's such a big deal that they open under VS by default. For HTML you can either switch to the "Design" view or right-click the file and select "View in Browser". Not ideal but better than not having the documentation as part of the solution IMO.
The samples have docs? Wow. I didn't know. I guess I am one of these 'stupid users'.
Why didn't I know? Because I don't look through every file in a zip file. When I see something called 'readme', I usually don't read it, since I know what the file contains -- a project and source.
Maybe the documentation should be called 'documentation', to make this clear?
Thanks again for your efforts to improve. :)
> Since Visual Studio "remembers" the open documents from a previous session, can you configure the .sln file in such a way that the .htm docs are already opened when you open the solution?
I believe the SpaceWar kit does this when you create it from the list of project templates, but that may be a feature of the template system, not the solution.