Announcing the C++ FAQ

In addition to CppCon announced earlier this week, today the Standard C++ Foundation is pleased to announce a new unified C++ FAQ. The following introduction was written by Herb Sutter.

 

For the past 18 months, a small group of us led by Marshall Cline and myself have been hard at work on making a unified C++ FAQ available here at isocpp.org, as a wiki whose editing can be crowdsourced to keep it up-to-date with current information about modern C++.

The unified modern C++ FAQ is now ready to launch, and you can find the current content here:

C++ FAQ

The following is some background information about this project.

History and Goals

Until now, there have been several different overlapping FAQs, including notably:

  • Bjarne Stroustrup’s FAQ pages
  • Marshall Cline’s popular C++ FAQs Online
  • at least three different StackOverflow C++ FAQs in some form, last time I looked
  • and many others

However, in practice we noticed several difficulties with this status quo:

  1. Fragmentation: The existing FAQs are fragmented, so people often have to consult several of them in order to find a single answer. On the other hand, they frequently also overlap in their contents, which creates redundancy and sometimes inconsistent treatments of the same question.
  2. Staying up to date: They all (even Bjarne’s) contained some out-of-date material, because it’s just hard work for a single author or small group to maintain a good and always-updated FAQ.
  3. Legacy search rank: When people search for information about C++, search engines often lead to pages that are highly ranked because they are well established -- they have been available for a long time and are widely linked-to. But since C++11 in particular has changed modern C++ style and recommendations, much of this popular information has now become dated or incomplete.

To improve this, here are the following major goals of the new FAQ and how we are achieving them:

  1. Solve the fragmentation problem: Provide a unified merged FAQ, starting as a union of Marshall’s and Bjarne’s FAQs. Marshall and Bjarne (and Addison-Wesley) have graciously agreed to provide their FAQ contents as seed material to be the initial content of the FAQ. Marshall Cline has worked hard to import his FAQ into the new FAQ via his automated tools, and I have recently completed hand-editing over 50,000 words of Bjarne’s FAQ into the new FAQ wiki structure.
  2. Solve the up-to-dateness problem: Provide wiki-based crowdsourced editing and maintenance. Any qualified C++ expert can and should be able to add to and improve the FAQ -- including all committee members and the scores (possibly hundreds) of regular high-quality contributors on StackOverflow and other sites. Marshall Cline in particular has worked tirelessly for the past year to produce a robust wiki-based mechanism with good collision detection and resolution. (Note: Much of the imported FAQ information has already been updated, but much still needs to be done -- you can help by using the "recommend an improvement" on any FAQ title to let us know. More on that feature below.)
  3. Solve the legacy websearch problem: When people search for C++ information, they should quickly get to the latest isocpp.org FAQ. This will be simple thanks to Marshall’s and Bjarne’s cooperation: Currently much of the websearch traffic goes to their FAQs because of their long history and pagerank. Both Marshall and Bjarne will be updating their FAQs to either forward or link to the new FAQ on a per-FAQ level. (To enable this, we have maintained the internal FAQ tags Marshall was already using, and I kept a careful index mapping from Bjarne’s FAQ pages#tags to the new tags so that he can easily provide redirects.) This way, the isocpp.org FAQ should quickly become the de facto top search result for C++ FAQs and other C++ information.

cpp-faq-example.PNG

We’re also trying to provide additional features:

  • Provide new FAQ sections for community information. This includes things like "User Groups Worldwide" and "Partial List of ISO C++ Committee Members" FAQ sections.
  • Provide new FAQ sections for "What's new in C++11" and "... in C++14." This makes it easier to see "What's different if I already know [a certain previous standard supported by my compiler]."
  • Provide new FAQ sections for "C++ for {C#/Java | Objective-C | C | C++98 } developers." Some of these have already been created with seed content, but need more information from experts in those areas. We hope crowdsourcing will fill this gap relatively quickly; one new FAQ per contributor scales really well with lots of contributors while being a light load for everyone.
  • Provide a new FAQ section for "C++ Myths and Urban Legends." This will help socialize correct information by providing answers to common objections and misconceptions. C++ isn’t perfect and shouldn’t be presented that way, but it’s not nearly as imperfect as frequent incorrect claims would make it out to be. Misinformation helps no one, and we can deal with common misunderstandings here. Again, this currently contains some seed content; more to come.
  • Provide a way to subscribe to the latest/freshest information: RSS feed for FAQ changes. We've created an RSS feed for FAQ change diffs (link also available in left sidebar while in the FAQ) so that anyone can subscribe to a stream of diffs of current changes as they happen, including new FAQs and updates to existing FAQs. In the past, updates to the preexisting FAQs were often buried and undiscoverable, making them less useful than they could be. This way, people who care can easily be informed about new material, and suggest further edits.
    cpp-faq-recommend.png
  • Provide a way for anyone, not just FAQ editors, to suggest improvements. If you hover over any FAQ's title bar, you will see not only a permalink icon, but also an icon where you can "recommend an improvement to this FAQ" including to suggest new FAQs not yet in the list.
  • Provide a "moderated/curated" experience by having designated FAQ editors, but allow lots of people to become FAQ editors. Today there are already over 50 FAQ editors. If you offer good suggestions via the public "recommend an improvement" links, it probably won't be long before you start seeing Edit links appear when you visit the FAQ pages.
  • Provide a FAQ Discussion forum. For those interested in minutiae or sending suggestions directly to FAQ editors, you can subscribe to the faq-discussion forum, also available by email at faq-discussion@isocpp.org (email faq-discussion+subscribe@isocpp.org to subscribe by email).

Acknowledgments

Our huge thanks go out to Marshall Cline who has put in a vast amount of volunteer work to make this possible, and also to Bjarne Stroustrup, Eric Niebler, Marshall Clow, Peter Gordon, Pearson/Addison-Wesley and the many other FAQ editors who have already made improvements -- all of these people have already contributed a lot of work and help to this. Thank you! And thanks again to everyone who has worked hard to make this possible.

Herb

 

Add a Comment

Comments are closed.

Comments (5)

0 0

Mantosh Kumar said on Mar 22, 2014 06:30 AM:

Wow....thanks to isocpp and Herb for releasing it at one place.....going forward this link would be bible for all kinds of C++ related FAQ...This is priceless.....

Mantosh
0 0

Mantosh Kumar said on Mar 22, 2014 06:33 AM:

You did hand-editing over 50,000 words of Bjarne’s FAQ into the new FAQ wiki structure!!!!!!..... smile...
5 0

Bjarne Stroustrup said on Mar 22, 2014 10:40 AM:

Yes, Herb deserves credit for a major piece of work.
3 0

Clayton Weaver said on Mar 23, 2014 10:27 AM:

Magnificent! I'm glad that there will be a factual FAQ in one spot. So tired of seeing all these FAQs that are based off misinterpretations of the language or standards. I'm sure Bjarne will agree that Sutter and Cline can't get enough praise and credit for this large undertaking.
0 0

Agentlien said on Mar 24, 2014 01:08 AM:

This is great news!

I've often used Cline's and Bjarne's FAQs as a quick reference guide and I've learned tons from these resources. Having a coordinated resource like this is more than I'd hoped for.