What's New in Help for Visual Basic 2005 Beta 1
Robin A. Reynolds-Haertle
Visual Basic User Education
Microsoft Visual Basic 2005
Summary: Describes the new features in the Help experience for Visual Basic 2005 Beta 1. The changes include distinguishing Visual Basic from other languages, more task-oriented topics, and an emphasis on code examples. (8 printed pages)
Note This article applies to a prerelease version of Visual Basic 2005, which is subject to change in future releases.
Supporting productivity is our key theme for the Visual Basic 2005 documentation. Our goal is that Visual Basic programmers, from the beginner to the experienced corporate developer, can build applications for Windows, the Web, and mobile devices with Just in Time Help. We provide abundant code examples, clear and concise task topics (called "How to" topics), and guidance to the developer for making informed choices during development.
The help topics in Visual Basic 2005 have a new look and feel, shown in Figure 1.
Figure 1. New look and feel for Visual Basic help documentation
- Colors and layout are updated.
- Syntax blocks, code examples, and notes are called out in shaded boxes.
- Sections are collapsible. In Figure 1, the Parameters section has been collapsed so that you can see the Syntax and the Remarks at the same time. The Help system remembers which sections you've collapsed. Never want to see the Thread Safety section again? You don't have to.
- With the Language Filter, you can display just the Visual Basic code in a topic. This feature isn't new, but it is easier to find.
- With the Copy Code button, you can copy a complete code example from a help topic to the Clipboard with one mouse click.
One approach to Visual Basic development is to build programs by combining smaller application units. We're supporting this approach by trying something new—an emphasis on "How to" topics. When considering new features, the first question we ask is "What does the developer want to do with this?" instead of "What does this feature do?" We have greatly expanded the number of task topics in the Visual Basic documentation. As an example, the overview topics on arrays have been replaced with numerous task topics. Instead of trying to figure out in "Array Usage" how to create a jagged array, you'll find a topic specific to that task, "How to: Create a Jagged Array." We've changed our emphasis in writing topics to get right to the point and describe the task step-by-step. Instead of having to read long discussions followed by code and instructions, you'll find the code and instructions right at the beginning of the topic. The detail is still there, but if all you want is the task information, we've saved you a few mouse scrolls.
Even with all the great designer tools in the IDE, creating applications is about writing code. In Visual Basic 2003, we responded to customer requests for code by creating numerous Code Example topics, with the code right at the beginning of the topic. In Visual Basic 2005 we're putting even more emphasis on code.
Copying Code Made Easy
With the Copy Code button, you can copy a code example from a Help topic to the Clipboard with one mouse click. That feature, shown in Figure 2, is available on all the code in the documentation set.
Figure 2. Copy Code feature
Adding Code Snippets to Your Application Supported
Visual Basic ships with an IntelliSense code snippet library, which consists of 280 pieces of code. You can add these chunks to your code and edit them using the pointers the code contains. The code snippets are available to you when you right-click in the Code Editor and click Insert Snippet.
Code snippet tasks range from creating a custom exception, to sending an e-mail message, to drawing a circle. The library is extensible. You can create code tasks that suit your business needs and add them to the library. You can also download more library tasks from third-party software vendors and Visual Basic community sites.
So, what's the connection to Help? Each code snippet has a closely related Help counterpart. If you need additional information on just what the snippet is doing, go to Help for the detailed information.
Help-based Samples Included
Visual Basic 2005 ships with more than 60 sample applications. Half of these samples are completely new for this release. These new samples were written by the product team, the same people that designed, implemented, and wrote about the new features. Even samples that aren't new are updated to use the latest Visual Basic features. Samples cover application development, data tasks, Windows Forms programming, security, and language features. Each sample is a complete project that can be copied to the local computer, loaded into the IDE, and run.
Starter Kit Walkthroughs
A starter kit is a project that can be shared. A starter kit includes code samples that compile, Help in the form of a guided walkthrough, and other helpful resources to enable you to learn new tools and programming techniques while building useful, real-world applications. Visual Basic 2005 Express Edition ships with one starter kit, the DVD Collection.
If you can't find the topic, it doesn't do you any good. You'll find some of the most noticeable changes in this release when looking for information in searching the documentation.
How Do I?
In keeping with our emphasis on tasks, we've added a new page to the Help browser, named "How Do I?", shown in Figure 3. Designed specifically for Visual Basic users, this page includes links to the most common application areas. Each area listed is a link that leads to task topics or to community forums. Also included on this page are links to community content, including MSDN, online code samples, and the Knowledge Base.
Figure 3. How Do I? page
Search has a new look for Visual Basic 2005, as shown in Figure 4. You can now filter the documentation based on language, technology, and topic type. Topic types help you find the kind of content you want. If you want an in-depth understanding of a technology, choose "Articles and Overviews." If you are only interested in looking at code, choose "Contains Code." If you think your problem is a known bug in Visual Basic, try restricting your search to "Knowledge Base."
Search is also the portal to the Microsoft community and the developer community. "Post a Question" directs you to several newsgroups discussing Visual Basic development. If you want to send feedback to the Visual Basic product team, choose "Send Feedback."
You'll find some feedback mechanisms in the documentation.
- Documentation feedback: If the code is incorrect, the content is incomplete, or the content is wrong, you can send feedback directly to the writers using the link found at the bottom of every topic. The link is titled "Send comments about this topic to Microsoft."
- Product feedback: If you have feedback about Visual Basic or Visual Studio, you can send it directly to the product team using the Product Feedback site at http://labs.msdn.microsoft.com/productfeedback/. You can also send your documentation comments here. To use this site, you'll need to register with a Passport account.
- Community feedback: On the "How Do I" page you'll find links to post questions to various newsgroups.
Visual Basic isn't just another managed language. It's designed with a particular group of developers in mind. Our Help strategy is designed for them, too.
We've made a real effort to create a view of the content that provides a Visual Basic perspective. This simplifies the topics because they contain only Visual Basic code and comments, and makes it easier to find Visual Basic-specific information. Within the dedicated documentation section, the user education team has written several sections to address different users and applications.
- Visual Basic Guided Tour
The guided tour is designed for the new user, and requires no previous knowledge of programming. The guided tour consists of a series of connected, short step-by-step tutorials, with instruction on a specific topic.
- Help for Visual Basic 6.0 Users
Users of earlier versions of Visual Basic have invested time and effort in learning the intricacies of Visual Basic. While many things have changed with the introduction of the .NET Framework, the overall experience remains essentially the same. The focus of this component is Visual Basic 6.0 developers now using Visual Basic 2005. It includes information on mapping between Visual Basic 6.0 and Visual Basic 2005 concepts, best practices for upgrading, and troubleshooting information.
- Upgrading Applications in Visual Basic
Upgrading discusses how you can upgrade programs created with earlier versions of Visual Basic to the new version of Visual Basic.
- Developing Applications with Visual Basic
This content guides you through Visual Basic productivity features. Developing applications with Visual Basic is more than just writing code. In the IDE, the features include improved data support, IntelliSense code snippets, edit and continue, and exception help. The addition of My to the language provides shortcuts into the .NET Framework.
- Visual Basic Language Tour
Visual Basic supports a number of common programming constructs and language elements. This language tour walks through all the essential elements of programming with Visual Basic.
The reference content is the first stop for F1 help (also known as context Help). In this version, the reference content has the same look and feel of .NET Framework reference and has design updates to improve online scanning.
Visual Basic 2005 Help ships with more than 60 sample applications, which are complete projects. Each explores a feature of Visual Basic, and is a great starting point for your own applications.
Since there are several managed languages (Visual Basic, C#, J#, just to name three) and many contributors to the code examples in the documentation, it's no surprise that sometimes the code examples in Visual Basic look a little bit like some other managed language. In those cases, you may not be seeing the full breadth of language features. To remedy this, we've established coding guidelines for Visual Basic code throughout the product documentation. We've published the detailed guidelines in the documentation with the samples. Here's a short list of our high priority guidelines to give you an idea of our direction with these guidelines.
- Use the Handles clause: It's more natural, especially with the designers, to use Handles for event hook up than the AddHandler statement. Visual Basic supports both.
- Use the With statement: The With statement, available only in Visual Basic, simplifies repetitive access to the same object.
- Use short instantiation: Use
Dim spot As New Dograther than
Dim spot As Dog = New Dog. The second example is clearly written from the C# perspective.
- Use My or the Visual Basic Runtime: The Runtime and My provide quick access to .NET Framework features.
- Use MsgBox instead of the Console: The Windows Application, not the console application, is an old standby for creating throwaway test applications. Using MsgBox reinforces the idea that we're using Visual Basic to write Visual Basic examples.
- Use "&" to concatenate strings: Using + instead of & for strings concatenation is more likely to result in bugs.
Our goal in the Visual Basic 2005 documentation is to support programmer productivity. The documentation contains more code, more "How to" topics, and more conceptual material to support this. To make finding this information easier, we've made significant changes to searching the documentation. We've also added more direct access for feedback to the Visual Basic product team.