I believe there is a tutorial page missing right after it discusses breakpoints - at this point it must explain how the user can view the values of program variables, it is one of the most important features of a debugger.

It must also discuss how to view registers, memory etc.

And in general it is not very clear on how you compile/build/upload/stop the current debug session - what happens to the code running already

Actually it does not explain well, or in the right place, that the debug code downloaded to the Arduino board is a special debug code .

I believe the documentation should start with a top to bottom overview before it delves to talk about "exotics", for example breakpoint on a variable change.

If a user has never used an IDE before, and is lacking understanding of basic concepts, this all should be in other sections. Currently it is all mashed together: information for total beginners, expert information for advanced settings, and missing vital information as I mentioned above. So there should be three sections: (a) how to use a "Visual Studio IDE", what to expect to see in it (for complete beginners), (b) top to bottom approach of the Visual Micro system, and (c) advanced concepts

Hi,
thank you for the feedback about the documentation. As Tim said before, it helps us improve the documentation over time.
Let me reply to your statements:

"A tutorial page missing right after it discusses breakpoints"
You're right. I will move the section about reading variables further up on the page, because it might be more important than the breakpoint advanced features. 

"It must also discuss how to view registers, memory etc."
Using C++, there's really limited need for viewing registers and fixed memory locations. You never have control over where the compiler puts things, so you better watch variables rather then memory locations and registers.

"And in general it is not very clear on how you compile/build/upload/stop the current debug session - what happens to the code running already"
Did you recognize the page called "How to Stop your Sketch, Recompile, and Run". Should it (or a link to it) put somewhere else?

"Actually it does not explain well, or in the right place, that the debug code downloaded to the Arduino board is a special debug code ."
There's this page which explains how Visual Micro works, we didn't put it in the table of contents, but it is references on one of the pages explaining debugging.

"I believe the documentation should start with a top to bottom overview before it delves to talk about "exotics", for example breakpoint on a variable change."
We decided not to do it this way, because then the documentation would become more of a textbook instead of a reference -and much bigger-, but it's a matter of taste. Maybe we'll focus on the order of topics within the pages, beginning wiith the most basic and going on to the more advanced.

"If a user has never used an IDE before, and is lacking understanding of basic concepts, this all should be in other sections. Currently it is all mashed together: information for total beginners, expert information for advanced settings, and missing vital information as I mentioned above. So there should be three sections: (a) how to use a "Visual Studio IDE", what to expect to see in it (for complete beginners), (b) top to bottom approach of the Visual Micro system, and (c) advanced concepts"
Visual Studio was written by several hundred developers. It would exceed our capabilities to write a manual for Visual Studio. There are lots of good web sites out there, including MSDN, that explain Visual Studio. However, the basic concepts, like solutions and projects, are part of the Visual Micro documentation.

Kind regards,

Heinz Kessler
Visual Micro