Did you know our samples have docs?

re: Did you know our samples have docs?

xPox — Mon, 26 Jul 2010 04:16:37 GMT

Like CatalinZima mentioned, on the Sample Details page for each sample, there should be a separate link in the downloads section just for the documentation. This makes it very visible and is where I would expect to find it.

That being said, the sample documentation I've looked through is usually not very helpful anyway. They are often very vague and usually assume the user is an advanced programmer.

Like Miguez stated, a video going over each section of code would be much more helpful.

re: Did you know our samples have docs?

fer — Wed, 07 Apr 2010 19:26:02 GMT

I didn't noticed they all had documentation, and know many samples start to make sense...

You could put the doc in the main folder, and the rest of the files in another folder, so when you open the project folder you find just the doc and another folder, just two thing makes it easier to realise that doc exists.

re: Did you know our samples have docs?

BShields — Sun, 30 Nov 2008 18:59:04 GMT

> 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.

re: Did you know our samples have docs?

Jason Doucette — Mon, 06 Oct 2008 21:02:03 GMT

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. :)

Take care,

re: Did you know our samples have docs?

Kevin Westhead — Sat, 27 Sep 2008 03:44:05 GMT

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.

re: Did you know our samples have docs?

Shazen — Wed, 24 Sep 2008 22:36:12 GMT

I especially enjoyed "Snow Crash"

re: Did you know our samples have docs?

Lynch3 — Wed, 24 Sep 2008 20:43:56 GMT

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...

re: Did you know our samples have docs?

DrJBN — Wed, 24 Sep 2008 20:34:03 GMT

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.,

Documentation_for_MultipallLighting_sample.html

re: Did you know our samples have docs?

miguez — Wed, 24 Sep 2008 20:28:41 GMT

Hi Shawn,

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.

Best regards,

re: Did you know our samples have docs?

Shawn Hargreaves - MSFT — Wed, 24 Sep 2008 19:27:31 GMT

> Can you add the document to the solution and just give it a "do not compile" setting?

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.