Last year, we made the decision to go on-line with the API help and documentation. Despite the initial negative reaction from some of our customers, I still think it was the right decision, and we went the same route this year.
Missing documentation is bad, but inaccurate, incomplete documentation can be even worse. Having the documentation on-line allows us to update it at any point in time and improve it over time. Last year, we were able to add additional articles to the Developer's Guide after the product shipped. We would not have been able to do it if the documentation resided locally on your machine. And in the future, we are planning to have more releases/improvements for the documentation as new articles and samples are written.
But this series is about Jay Peak and what we have done in the new release of Civil 3D, and when it comes to documentation, we have done a lot. Some results will show immediately, others will appear very soon, and like I said, we will deliver more improvements in shorter cycles. Let's take a look at what's new and how you can get some help.
Where's the Help?
You can access the API documentation from the AutoCAD Civil 3D 2013 WikiHelp site. This site provides access to all the product documentation as well as the API. You can find articles, tutorials, videos, and links to other resources, and it is the first place to find information about Civil 3D in general. You should add that location to your bookmarks and keep it handy.
What's New with the Developer's Guide
This year, we were able to add several articles to the Developer's Guide that cover, not only the functionality in the 2013 release, but also the functionality made available in 2012 for which we didn't have any new content. Because of our ability to update the documentation at any point in time, we added the applicable articles to the 2012 Developer's Guide to keep things up-to-date.
The new version of the Developer's Guide includes articles for the Surfaces .NET API introduced last year, as well as articles for the COGO Points .NET API, which is new to the 2013 release. These articles go deep into the functionality of the API and are a great resource to understand the design and implementation of the features.
Introducing the New Reference Guide
One of the biggest efforts this year regarding the API documentation has been the brand new Reference Guide. We spent quite some time researching tools and processes that would allow us to provide a better reference for all the available APIs and make them more valuable to all of our customers. Some improvements you will notice right-away; others will appear over time. This is an ongoing effort, and we are committed to it.
The first change you will notice is the new look and feel of the Reference Guide. We did some research of documentation tools that generate HTML documentation ready to be posted on-line and that can be integrated with our build process. The result a more modern, up-to-date Reference Guide generated every time we build Civil 3D. This allow us to release updates at any time including the latest and greatest information. We can fix any problems we find, and we can make changes according to the feedback we receive (more on that below).
One of the most requested improvements to our documentation is to provide more and better examples. You speak, we listen. The new Reference Guide allows us to embed sample code for each of the classes and members we document. You will notice that some of the new features are already providing small snippets of code that demonstrate their use. Again, we can update this over time, and we will be providing more and more code samples.
We created a new documentation review process to insure the quality of the documentation is the highest. You will see that classes, methods, and properties are better documented, and it is likely they will get even better in the near future. Of course, good documentation is kind of subjective, so we will need your help and feedback with that, which leads me to the next improvement.
Feedback links in the Reference Guide have been broken for quite some time. Not any more. Not only do they work, but submitted feedback does not go into a bucket that no one is monitoring anymore. When you submit your feedback it goes directly to me (and other members of the API engineering team). That's right, you submit your feedback, I get an e-mail. I have total confidence in the community to provide us with comments and suggestions on how to improve things even more, and find problems with the documentation where things are not correctly stated or do not work as described. I am also sure all of you will be very respectful to the engineering team when submitting your feedback and that I will not need to ignore/delete your e-mails.
How about getting help right in Visual Studio 2010? Well, you got it. During the process that generates the Reference Guide, an XML file is created that has all the information to point Visual Studio in the right direction. You can download this ZIP file, extract the XML file into the AutoCAD Civil 3D 2013 installation folder (usually, "C:\Program Files\Autodesk\AutoCAD Civil 3D 2013"), and restart Visual Studio, if needed, and you will get help information for each of the API classes, methods, and properties right in your Visual Studio tool-tips as you type the code. Isn't that a dream come true?
What Else is Coming Up?
I recognize that for some of you local documentation is important. We are in the process of making the documentation available for download. We are looking at different alternatives because we want to have the same flexibility to update the downloads as we do with the on-line documentation. In the near future, I will update this post to provide links to the hosted files, so you can download, not only the Developer's Guide and Reference Guide, but also all the samples (as working code) included and embedded in the Reference Guide.
As you can see, we did a lot of work to bring you as much help as possible. There is still room for improvements, but we are at a point where changes can be easily propagated, which will allow us to provide a better service in the future. I think we are moving in the right direction, and I hope you participate in the process by telling us what more can we do to help you.
Update: Documentation Available for Download
As promised, we have made the new documentation available for download. You can access it now, and please report any problems with the links below.
Reference Guide. The ZIP file contains the entire Reference Guide in HTML format. You can extract the files and create a shortcut to index.html for quick access.
Developer's Guide. We have also provided a PDF with all the articles in the Developer’s Guide. We’ve found some formatting issues with certain images caused by the new documentation system in use by the User Experience group. They are investigating the problems, so please have a little patience. Still, the Developer’s Guide is full of great information, and this PDF should allow you to bring it with you everywhere.
Reference Guide Samples. All the Reference Guide samples are also available for download. This download contains a Visual Studio 2010 solution and projects with working code written in C# and VB.NET. As more samples become available, we will update this file, so you can download it and play with it.
Visual Studio Help Index. This download is a great resource. Extract and copy the included file into your Civil 3D installation directory, and Visual Studio will show you documentation information as tool-tips right from the Reference Guide.
Subscribe