Visual C++ docs: the future is… soon!

Eric

November 8th, 2016

We on the Visual C++ documentation team are pleased to announce some changes to the API reference content in the following Visual C++ libraries: STL, MFC, ATL, AMP, and ConcRT.

Since the beginning of MSDN online, the Visual C++ libraries have documented each class member, free function, macro, enum, and property on a separate web page. While this model works reasonably well if you know exactly what you are looking for, it doesn’t support easy browsing or searching through multiple class members. We have heard from many developers that it is painful (sometimes literally) to click between multiple pages when exploring or searching for something at the class level.

Therefore we have re-deployed the above-mentioned reference content as follows:

For STL:

Each header will have a top level topic with the same overview that it currently has, with links to subtopics, which will consist of:

one topic each for all the functions, operators, enums and typedefs in the header

one topic for each class or struct which includes the complete content for each member.

For MFC/ATL/AMP/ConcRT:

one topic for each class or struct

one topic for each category of macros and functions, according to how these are currently grouped on MSDN.

We strongly believe this change will make it much easier to read and search the documentation. You will be able to use Ctrl-F to search all instances of a term on the page, you can navigate between methods without leaving the page, and you can browse the entire class documentation just by scrolling.

Non-impacts

1. Reference pages for the CRT, and the C/C++ languages are not impacted.

2. No content is being deprecated or removed as a result of this change. We are only changing the way the content is organized.

3. None of your bookmarks will break. The top level header and class topics all retain their current URLs. Links to subtopics such as class members and free functions will automatically redirect to the correct anchor link in the new location.

4. F1 on members, for now, will be slightly less convenient. It will take you to the class page, where you will have to navigate to the member either by Ctrl-F or by clicking the link in the member table. We hope to improve F1 in the coming months to support anchor links.

Why now?

Documentation at Microsoft is changing! Over the next few months, much content that is now on MSDN will migrate to docs.microsoft.com. You can read more about docs.microsoft.com here at Jeff Sandquist’s blog. On the backend, the source content will be stored in markdown format on public GitHub repos where anyone can contribute by making pull requests. Visual C++ has not moved to the new site just yet, but we are taking the first step by converting our source files from XML to markdown. This is the logical time to make the needed changes. By consolidating content, we have the additional advantage of more manageable repo sizes (in terms of the number of individual files). More content in fewer files should make it easier for contributors to find the content they want to modify.