You’ve Got Some Explaining To Do So write an FAQ! Rich Sands, Simon Phipps / FOSDEM 2018 Community Devroom

Let’s just add this defensive patent grant along with the license. More rights to devs, stops the trolls, what could go wrong? Great idea! I’m on it...

You just don’t understand … this is no big deal, really… could we please have a do-over? …

We’ve been to that place

Q: Why write an FAQ? ● Primarily to learn the answers yourself! ○ Test and refine strategy. ○ Get everyone to agree. ○ Create consistent messages. ○ Establish trust through transparency. If you can answer the hard questions intelligently, you’ve got a coherent strategy and message.

Q: Who is the audience for my FAQ? Developers! Your most important, and toughest audience. Satisfy them and everyone else will be fine.

Q: What is most important to developers? Transparency! The truth, the whole truth, and nothing but the truth. Yeah, it's hard. But that is why it works.

Q: Do I have to answer the hard questions too? ● Yes! Devs know the hard ?s and expect answers. Q: What if they won’t like the answers? ● Don’t “spin”. Truth earns respect and trust, even if it isn’t what they want to hear. Maybe they tell you they won’t use your technology. If that is a problem, change your strategy. Q: What if we don’t know the answers? ● Say “We don’t know”.

Example from the Open Source Java FAQ Q: Why didn't you choose a license like BSD or Apache v2? A: Sun had several objectives in mind in choosing the license for the JDK source code. We wanted to: ● Drive more adoption of Java SE, especially within GNU/Linux distributions. ● Minimize the likelihood of incompatible forks. ● Engage a broad cross-section of the open-source communities. ● Protect and enhance the investments of those who have licensed and chosen to support the Java platform. After extensive analysis and consultation with experts both inside and outside of Sun, we determined that of the choices available, the GPL v2 + Classpath exception license paradigm is most likely to achieve these objectives. We know that this choice is unlikely to please everyone but we believe it offers the best balance of opportunity for developers and Sun. Hard question. Unpopular, but complete and truthful answer: drive adoption, while preserving the value of Sun’s binary Java licensing business and protecting compatibility. “Balance” - meaning, Sun was unwilling to choose a license that its leadership believed would damage Java’s “Write Once, Run Anywhere” value proposition, or Sun’s OEM licensing business, but wanted the benefits from open sourcing the platform. This was the compromise arrived at after months of fierce internal debate.

Q: What should we put in the FAQ? Characteristics: ● Transparent. ● Complete. ● Intellectually deep. ● Answers to hard questions. ● Good navigation. ● Motivation: why, not just what. Topics: ● What you’re announcing. ● General and goals. ● Business model: how everyone succeeds. ● Legal: licenses, I.P., terms of participation. ● Schedules, roadmaps, releases. ● Community and infrastructure. ● Ecosystem questions. ● Where to find more information. The general FAQ doesn’t replace documentation. Have a separate FAQ for technical usage questions.

Q: This seems daunting! How do we get started? ● Start early! ● Brainstorm ?s with a cross-functional, empowered team. ● Divide and conquer to develop answers. ● Expose and resolve strategic conflicts and weak planning. Use the FAQ to engage leadership, force strategy decisions and concurrence.

Q: Who should write the FAQ? ● Someone who is: ○ A marketing/messaging expert, ○ A compelling and clear writer, ○ A great team leader, ○ Skilled at engaging with your developer community. Your community manager, of course!

Q: How do I get my leadership on board? ● The strategy must have a clear path to deliver what leadership wants. To gain alignment, they might need to: ○ demand compromises, ○ change incentives, and ○ hold everyone accountable. ● They’ll have to embrace transparency. ● Driving adoption often requires them to give up control. If leadership isn’t on board, watch out!

Q: Legal says transparency is too risky. Now what? ● They’re right! Explanations and motivations in the FAQ open your organization to scary new legal risks. ● Legal language defines rights and responsibilities with certainty. Plain language seems risky to lawyers. ● But developers aren’t lawyers, and don’t hire lawyers. They need the FAQ to explain in plain language. Hard to solve: Leadership must charge legal with minimizing risk, but ultimately with being a partner in success.

Q: Why is executive backing so critical? ● On Nov. 12, 2006, one day prior to Sun’s initial code drop for OpenJDK, a senior executive tried to kill the Open Java FAQ, replacing it with a short, spin-heavy version. ● By then, enough other senior executives were sold on radical transparency to turn back this coup attempt. ● But key employees had to threaten to quit in protest first. Be sure your top leaders have your back!

Q: Any tips on review, publishing, comments? ● Use an authoring tool with change tracking. ● Publish near code: Github Pages, an organization’s forge, wherever your community lives. ● Simple: linked HTML TOC, number the questions, give each a URL, avoid “eye candy” Javascript. ● Moderate but publish all comments, both good and bad. ● Evolve your FAQ. Include “What's New?”, version/date. Don’t get fancy. Follow your community’s norms.

Q: What about other marketing, communications? ● As an agreed, consistent, detailed set of messages, the FAQ should be a primary source. ● The FAQ can streamline MarComm. Nearly every ? will be answered in depth, and the FAQ can train spokespeople. ● Your FAQ can also inform speaker guides, keynotes, executive messaging. When even hard questions have clear and true answers, staying “on message” becomes much easier.

So where did all this get us?

Q: How do I convince our old-school lawyers and executives to embrace radical transparency? ● First prove it works, with a pilot project. ● Introduce your leadership to community thought leaders. ● Expect pushback. You’ll know you’re getting there when your executives are uncomfortable. Patience and demonstrated success wins over skeptics and changes culture.

Resources ● The FAQ FAQ - an FAQ Rich wrote with a lot of this content: https://rsandsconsulting.com/the-faq-faq/ ● The Open Java FAQ as archived by the Iced Tea project: http://icedtea.classpath.org/openjdk/java/faq.jsp.html ● Android: https://source.android.com/setup/faqs ● Creative Commons: https://creativecommons.org/faq/ ● Apache: https://www.apache.org/foundation/faq.html

(Frequently Asked) Questions? Rich: [email protected] Simon: [email protected] Rights information: Comics by Rich inspired by XKCD: https://xkcd.com/ Video © Sun Microsystems, licensed under a free license at Stallman’s request (we think GFDL or CC-BY-SA) Screenshots as copyrighted on pages captured, fair use claimed © 2018, Richard Sands and Simon Phipps, licensed CC-BY-SA 4.0 International (21 slides)