The FAQ FAQ

Updated November 2017

Introduction

faq What would a developer community be without a FAQ? It is a time-honored tradition to collect the key questions developers and others have about a project in the form of a “Frequently Asked Questions” document or FAQ. It is a common practice, because it solves some important problems that often crop up in building developer initiatives in a way that can really connect with developers and burnish your initiative’s reputation. It seems that a developer-focused FAQ should be a very simple, low-stress document, but in practice, the process of building a FAQ often forces a company and a community to face some of the existential questions that the shape the overall platform adoption effort and determine its success. That’s why the FAQ should be one of the critical planning documents for your developer initiative, and a driver for up-front coordination and strategic thought. If you can answer the really hard questions publicly, confidently, and truthfully, your messages will have consistency and transparency, and establish the trust and good karma that are critical to platform adoption initiatives. Not only will developers appreciate your candor, but your customers, partners, press and analysts will all thank you for a FAQ targeted toward developers, and lacking in spin. What better way to explore the whys and wherefores of FAQs than in a FAQ? So in the spirit of recursive marketing, here is a FAQ FAQ. Questions and comments welcome – they may become part of this document’s ongoing maintenance!

The Who, What, and Why of FAQs

FAQ Best Practices

Content and Coverage

Process and Overcoming Challenges

Resources

Can you point me to some good FAQs that illustrate these concepts and techniques?

The Who, What, and Why of FAQs

1. What is a FAQ?

A FAQ, or Frequently Asked Questions document, is a messaging document in the form of a series of questions and answers. The FAQ is supposed to cover frequent questions, but it can be used to capture all of the key messaging for a developer initiative in an easily browsed set of bite-size nuggets. A reader can home in on a particular issue, or read the whole FAQ to get a broad understanding of the project. The FAQ doesn’t just answer questions that have actually been posed, it anticipates key questions based on issues and characteristics of the platform and its community. TOP

2. Why should I write one?

The obvious reason is to capture answers in one place so that you don’t have to keep answering them in one-off communications. But there are many other reasons to write a FAQ that aren’t quite as obvious:

To test and refine your strategy through detailed team critiques that surface all points of view in a process that demands commitment and consensus.
To ensure that your messaging is internally consistent and drive strategic alignment across different teams in your organization.
To create a single definitive positioning document and authoritative factual reference that can be used by spokespeople to explain the project consistently to the world.
To establish trust through transparency. If you answer the hard questions truthfully and explain difficult topics clearly, including legal and licensing topics, developers will conclude you’re not trying to hide stuff from them, and be more inclined to trust you and participate.
To make it easy for new people both inside and outside of your organization to come up to speed, know what the project is, how to use it, and how to get involved.
To save yourself a lot of time, by creating an easy to use reference document that answers most questions people might have about your initiative. If you’re asked a tough question, you won’t have to scramble to create an answer that is consistent with everything else you’ve said before. You’ll already have such an answer ready to go.

If your developer initiative is non-controversial, licensed under one of the most popular OSI-approved licenses and on a popular repository system such as GitHub, with common, easy to understand contribution guidelines and requirements and an active and friendly developer community, you might not need this sort of FAQ! There are many famous projects with huge user and contributor communities that don’t need one, and skip doing the extra work. But if your organization has a difficult history with developers, your initiative could be misunderstood or seen as hostile to an existing community, or there is anything non-standard about how you engage with developers, an FAQ might be a great idea! TOP

3. Who reads these things, anyway?

Few people outside of your organization will read a FAQ in its entirety, but developers will read the parts that matter to them in deciding whether to adopt your platform, to participate, and to form their opinions. Others, including the press, analysts, licensees, customers, employees, investors, and competitors will read selectively or seek out specific answers. Most of your audience can make good use of a FAQ, and will, if given the opportunity. TOP

4. How do I create a FAQ for so many different audiences?

You don’t. You create a FAQ for developers, but make sure it answers everyone’s questions. But it has a single tone and approach, aimed at developers. Remember – you’re trying to influence them to adopt your platform. Speak to them! TOP

5. But who is my primary audience for a FAQ?

Your developer community is the primary audience for your FAQ. TOP

6. Does making my external developer community the primary target for my FAQ make it less useful for everyone else?

On the contrary, it makes it more useful for everyone else. Since developers are your most critical audience, and the least forgiving of spin and lack of transparency, targeting the FAQ at developers means that your other audiences will get a more unvarnished view of the project than they may be accustomed to getting. TOP

7. Why not create separate FAQs for each audience with the messages I want to go to each?

Because you must deliver a consistent, truthful, complete message to developers to gain their confidence. When you “spin” your answers for different audiences, developers will perceive your different messages as deceptive, and may call you out on it. Even though other audiences may be more forgiving than developers, they can and do talk to each other through forums, blogs, Twitter, and other communications channels. Honest, consistent communication turns this market conversation to your advantage, fostering trust and setting your company and initiative apart from those that strive to spin their marketing. TOP

8. I don’t buy that – I create separate messages for different audiences all the time – why won’t it work here?

Because the audience that matters for platform adoption – developers – is very intolerant of that kind of marketing. Trying to spin things for different audiences will alienate developers, the one audience you cannot afford to alienate. TOP

9. I want developers to trust us and participate. I want press and analysts to say nice things about us. I want customers to be confident in the platform and ready to invest in using it. How do I reconcile these goals?

The press and analysts know you are implementing a platform adoption strategy and will write nice things about you if the developers they ask for an independent viewpoint say they trust you, and are planning to adopt your platform and participate in your community. Likewise, customers know their investment in deploying your products will be safe if developers are engaged and leveraging your platform. With platform adoption strategies, your non-developer audiences will look to the developer community to be the thought leaders in deciding if your initiative is a success. After all, if developers do not adopt your platform, you won’t succeed, right? TOP

10. Are the press and analysts going to read a FAQ? Customers? My employees? Investors?

Yes, especially if you point them to it and make it easy for them to use and understand. TOP

11. How do I use a FAQ to foster consistent messaging?

Since you’re writing it for a single audience, and it serves as the central repository of “official” messages, the FAQ establishes consistent messaging. Your executives, spokespeople, sales department, and engineers will speak with one voice, because they have a powerful resource that gives them the words they need to articulate your message in unison. TOP

FAQ Best Practices

12. Ok I understand now why developers are the primary audience. What is most important to them?

Developers want the truth, the whole truth, and nothing but the truth. In a word, transparency. TOP

13. What do you mean by transparency?

Transparency is when you let others in on the actual motivations, thought processes, objectives and reasons, and all of the details, no matter whether they’ll like what you say or not. Of course you try to frame your answers in the best light but you don’t shade the truth to do so. And you expand on your answers enough so that readers understand why you’re doing what you’re doing, not just the objective facts. With transparency, developers understand your project much more deeply, and know what to expect. TOP

14. Why is transparency important?

If you put all of your motivations and decisions on the table, and on balance you’re largely protecting developers and responding to their interests, they’ll cut you some slack on the few areas where you don’t have their ideal answer. Earning that slack requires transparency. Developers need to believe that they have a complete picture of what you’re doing, so that they’re confident they won’t be surprised by any “gotchas.” Transparency gives them that complete picture. TOP

15. Do I have to answer all the hard questions too?

Absolutely. Developers are very sophisticated, and having been burned in the past and knowing how platform strategies play out, they know the hard questions already. They’re going to look for those hard questions, both to reassure themselves that you know what you’re doing, as proof positive of your transparency, and finally to gauge your responses and whether they’re comfortable with them. Answering the hard questions also goes a long way to easing “what’s the catch?” fears. You will cultivate trust if you are willing to shine a light on the hard issues and have complete, honest answers. TOP

16. What if my answers aren’t what developers want to hear?

You can be sure that you aren’t going to please them all. Developers are not a monolithic bunch. Even famous developer-centric communities like Apache and Debian do not appeal to all developers all the time. You do not need to be perfect. But you do need to be perfectly transparent. And if your answers are mostly self-serving, you probably won’t gain much adoption.

There are some famous counter-examples as well. The Apple iPhone App Store and Developer Program garners extraordinary developer attention despite its developer-antagonistic approval process and secrecy. Thats because Apple has some uniquely developer-friendly elements to their platform that cause developers to cut them much more slack than would be true for most other companies. The iPhone Developer Program features a very easy-to-leverage development model, a deployment and payment model far simpler than the competition, extraordinary end-user enthusiasm, a uniquely sexy, smooth user experience, and a unified, non-fragmented worldwide platform. These compelling advantages in the mobile application space overwhelm developers’ dismay at Apple’s control-centric and unfriendly dealings with individual developers.

In a nutshell, Apple makes it so much more efficient for developers to make money that they forgive them their bad behavior. If Apple’s competition were to even the contest in some of these other critical areas, developers would be less inclined to grit their teeth and put up with Apple’s iPhone Developer Program shortcomings. TOP

17. But the truth is – we have different goals than developers using our platform. For example, we want to make money, and they want it for free. How do I address this while staying transparent?

Just tell the truth! Developers expect you will need to eat. All but the most hard-core Free software advocates will understand that you have a business to run. If your decisions are such that for the most part, developers can leverage your platform as they need to in achieving their own goals, your different goals will co-exist. The one thing developers can’t forgive is if you try to fool them by hiding your true objectives and decisions behind “spin.” That is why transparency is the core quality of a good FAQ, and one of the most important characteristics of any platform adoption initiative. TOP

18. Is there always an answer that is both truthful, and is developer-friendly?

Not always. Sometimes you won’t please developers, and not all developers will agree on what is best, anyway. Being truthful about what you’re doing and why will earn you respect, and being transparent even when it is a difficult message helps to build trust. Even if developers don’t like everything you’re doing, they will be confident that they know the score. TOP

19. Can’t I just spin it to be both true and developer-friendly?

Sometimes you can. But spin inherently doesn’t sound truthful, and if you are shading the truth, developers will probably discover that and you’ll lose their trust. Of course, you want to give answers that put you in the best light, while remaining truthful. Transparency is developer-friendly. TOP

20. Why not just leave the hard Q&As out, then?

No one likes being put on the spot with hard questions. But because developer communities have been around for decades, there have been many examples both good and bad, and plenty of experience to inform your audience. Developers know where the traps are, and they will expect you to answer the hard questions. If you don’t, they’ll assume you have something to hide, and they won’t trust you. Answering the hard questions is usually a prerequisite to gaining adoption. TOP

21. What if we don’t know the answers to the hard questions?

Then say “I don’t know.” Those three words are a great way to create trust, because they are the truth. Sometimes you don’t even know what the hard questions are! Ignorance can be forgiven if you listen and respond quickly and always transparently. If appropriate, you can ask developers to contribute their ideas as well, engaging them and giving them the opportunity to help shape your answers. TOP

22. Won’t they read all that truth and transparency and decide they don’t want to adopt our platform?

They might! Usually, you will have a warning – developers can be very blunt. But if your answers are really that unfriendly to developers and your business imperatives mean you cannot change course, perhaps an adoption-led strategy is not the right one for you. This is a big warning flag – if you can’t create a transparent FAQ that will inspire developers to adopt your platform, how successful do you think your initiative will be? TOP

23. A meta-question: I notice you’ve structured this FAQ more as a conversation than independent Q&As. Why?

That’s right. Often the most difficult questions evolve from the answers to the more obvious ones. By structuring the FAQ to progressively illuminate the real issues and explain them, you lead the reader to greater understanding as they put concepts together. Illuminating issues over a sequence of answers is a good way to make sure you uncover the challenging questions completely. Building the FAQ as a conversation has another benefit: it can draw the reader in and get her to read more of the FAQ, fostering understanding and creating a stronger sense of transparency and trust. TOP

24. Do you really expect people to read a very long FAQ like this?

Not the whole thing. People usually will home in on their specific questions, and if those sections have depth and draw them into an intellectual discussion within the FAQ, they’ll read more. If they see that you’ve thought through the challenges and answer all of the hard questions, they’ll keep coming back for more, as they explore your initiative. The more engaging and easy to navigate your FAQ is, the more people will read, even with long FAQs. TOP

Content and Coverage

25. So, what are the critical elements of a great developer initiative FAQ?

In a nutshell:

Transparency.
Completeness.
Intellectual depth.
Answers to hard questions.
Good navigation.
Exposing motivations and processes – the why, not just the what. [TOP]

26. What topics should be covered?

It depends on what you’re doing, of course. For a large-scale initiative such as opening a large, well-known code base, you would want to cover at a minimum:

News and Announcements (if you are launching the project):
- What you’re announcing.
- Why it is significant, in a nutshell.
- What is new and what has changed, if your announcement is updating an existing initiative.
General and Goals:
- Description of your platform.
- What it does, components, a bit of history.
- Why it is important, how it can be used.
- How developers can participate.
- Key features of the initiative at a high level.
- Why the initiative – motivations and objectives for your company.
- Benefits for developers.
- Impact on other stakeholders – licensees, customers, end-users, whomever.
Business model:
- What is free in the interests of driving adoption, and what costs money?
- What is the motivation for this business model? What does your organization hope to accomplish?
- Nature of a purchase – one time or subscription? Service offerings?
- Why would a customer choose to buy the for-fee components of the project – benefits and value.
Licensing, Intellectual Property, and Legal:
- What are the terms of the binary API, source code, service offering licenses, and other component licenses?
- Why this licensing model?
- How does the business model complement the overall project objectives?
- What are developers’ rights and responsibilities? What are the company’s rights and responsibilities?
- Legal framework for participation: contributor agreements, site terms of use, etc.
Schedules, roadmaps, release structure.
Community and infrastructure, possibly including:
- Source code repositories.
- Ticketing.
- Collaboration tools.
- Project approval, committer status, governance.
- Details of how the code is structured, how to to access it, and requirements to build it.
- What access, if any, do developers have to trademarks and branding? How are trademarks licensed?
What are the connections between this initiative and other developer projects in the ecosystem? How does this initiative compare with and compete with other developer initiatives?
Where to go for more information. This can be sprinkled through the entire FAQ as appropriate.

Every project is different. The specific areas covered by your FAQ will depend on what you’re doing, how it affects your developer community, and the impact of your initiative on the ecosystem and market. Remember – transparency and completeness are the hallmarks of a good FAQ! TOP

27. Should there be just one FAQ or perhaps one focused on general stuff about the initiative, and another focused on technical details?

If developers new to your platform would benefit from a technical FAQ, by all means create one! It is probably best to keep the how-to questions separate from the what and why questions. Such separation lets the world assess the technical merits of your platform separately from business, legal, and community issues and benefits. If your initiative features a simple licensing and business model that is less likely to be controversial, it might be fine to combine your business and technical FAQs. Many famous projects have taken this approach successfully. Even so, consider writing those Q&As separately. Often the best technical FAQs are created by engineers, for engineers. TOP

28. Does a FAQ replace documentation? Does it replace other marketing collateral?

The FAQ does not replace technical documentation. Nor does it replace other marketing materials and web properties. But the FAQ can consolidate the core messages for your platform’s marketing in one place, making it a lot easier for your team to know how to position things, what aspects of your initiative need more explanation, and how to stay on-message and consistent across different marketing elements. TOP

Process and Overcoming Challenges

29. This seems so daunting! How do I get started?

Because this kind of comprehensive FAQ exists at the intersection of strategy, messaging, and execution, it can act as a catalyst for making decisions. If your organization can answer the hard questions, you’ve probably thought through the key strategic elements of your plan and you’ll be able to execute it with confidence. So start early! Establish a cross-functional team consisting of empowered representatives from these departments and functions, brainstorm as comprehensive a list of starting questions as you can, and then divide and conquer, assigning different pieces to the most appropriate team member to research and propose answers. This process will quickly shed light on where you have internal disagreements, and where your planning is weak. By starting early, you’ll have time to resolve the issues and shore up your planning. TOP

30. Who should be involved in crafting the FAQ?

You’ll need a leader who is a strong marketing/messaging expert and compelling writer, so that the end result has a strong, consistent voice and style. If possible, your lead writer should be someone familiar with developers, developer communities, and the norms of the open source world – your community manager, for example. This leader will be responsible for coordinating a large virtual team of senior contributors, and must be empowered by management to subcontract out parts of the FAQ. You’ll need representatives from your engineering, legal, marketing, sales, service, and other stakeholder departments who are expert in the specifics of your platform, and empowered by their management to get closure on answers and resolve issues. The very best FAQs include key representatives of your developer community to provide feedback, ideas and inspiration, an early warning system for potential sticking points, and a large measure of credibility for the final product. There is no better way to ensure transparency than to include developers in the process! TOP

31. Can I outsource the writing?

Possibly, but you’ll need writers who are exceptionally well-connected and familiar with your company’s culture, goals and objectives, and technology, and who also know how to write for a developer audience. That’s not to say it can’t be done, but for something as complex and potentially controversial as a comprehensive strategic messaging document in the form of a FAQ, you might spend more time managing the writers than you’d spend crafting it yourself, if you have the talent internal to your engineering or marketing organization. TOP

32. How do I get the executives and lawyers on board?

These two internal stakeholder groups are critical to the success of your platform adoption strategy. The challenge comes when they discover just what “transparency” really means. Your executive management team might discover that in order to execute an adoption-led strategy, they must demand compromises from nearly every group within the company, and change goals and incentives to motivate those compromises. For example, your OEM sales team may no longer be able to sell binary licenses for your platform technology, if your adoption-led strategy demands that you open-source your platform. Your company’s short-term revenue targets may need to be adjusted downward to achieve long-term revenue growth driven by a groundswell of platform adoption.

Your legal team may be just as challenged by the legal risks inherent in transparency. Offering developers an opinion as to what your licenses actually mean, goes against all of their instincts, training, and experience. But developers are not lawyers, and find all the intellectual property and licensing complexity of modern platforms a huge barrier to adoption. If you don’t explain it to them in plain English (or whatever language they speak!) you run the risk of your adoption-led initiative being stillborn.

Ultimately, these two groups need to see that your top management is committed to a platform adoption strategy, supports the compromises necessary to win, and holds your executives and legal team responsible for the strategy’s success. Beware if you can’t count on the support of your top leadership! TOP

33. My legal department says I can’t say XYZ, because it opens the company up to potential risks. Now what?

Your legal department is right! Platform adoption strategies expose your company to new, scary risks. For example, your platform may have a component such as a video codec, licensed from a third party under a field of use restriction. Perhaps the codec is licensed for use only in embedded applications, and not for applications that may be independently distributed and installed. If your platform licenses thus include such a field of use restriction, and you don’t explain what can and can’t be done with your platform in plain English for your developers, your platform might develop a “toxic” reputation for complex, legal encumbrances. Of course developers would prefer a license without such restrictions. But if they know what it says, and what they can do, they can decide whether to adopt your platform, or not.

But your lawyers may be extremely uncomfortable with offering that level of interpretation in the FAQ. They wrote the license using legal language that defines rights and responsibilities with certainty. They would rather that developers learn what they can and can’t do by consulting with their own legal counsel. What if a developer relies on the “squishy” explanation in the FAQ, and is sued by the third party that owns the codec? Could they in turn hold your company liable in that they relied on your FAQ? That is just one example. Your legal team may be able to find hundreds more. Each risk in itself may be very small, but when you add them all up and realize this is new territory with little precedent, you can begin to understand the hesitancy of your legal team.

This problem is a hard one to solve. If your leadership is behind the initiative, and charges your legal department with creatively minimizing the risks as much as possible, and educating management on the remaining risk levels, your lawyers may become your very best, most trusted friends. TOP

34. How can I manage the review process?

A FAQ can be a long, complex document. People who are contributing want to focus their attention on just the parts of the document that change from revision to revision. So a tool that shows changes, such as the red-lining capability in Microsoft Word or similar applications can prove very helpful. In addition, these tools often let you merge changes to a document from multiple sources, reviewing each change and approving or disapproving as you go. It is also helpful to create and review the FAQ over a series of editing cycles, in which a numbered version is distributed with a deadline for changes. The writer/editor of the document incorporates those changes, and another numbered version goes out. Because understanding exactly how the document changes from version to version is so important in helping reviewers stay on top of the process, collaboration tools that do not support red-lining, such as wikis, are usually a poor choice.

There are popular collaboration tools such as Google Docs, Microsoft Office 365, or versions of LibreOffice supporting collaborative editing that may prove valuable in coordinating a virtual team such as the one you’ll need in constructing your FAQ. If your organization has a favorite collaboration tool allowing for multiple authors working simultaneously together, such a tool could possibly streamline your FAQ review process. TOP

35. We don’t have all the answers yet. Heck we don’t even know all the questions! And its time to announce – what do we do now?

If you don’t have enough of your strategy baked such that the most essential questions about what you’re doing and why can’t be answered, should you be announcing? Consider that question carefully, because if you announce what you’re doing, then radically change your mind, you will undermine the trust you’re trying to establish with developers and put your whole initiative at risk. That said, if the fundamentals are in place but some of the details are fuzzy, you can truthfully say “I don’t know” to the harder questions, with a time-definite commitment in the FAQ promising when you’ll have an update and answer. You can release a “minimum viable FAQ” as long as you identify it as such, and follow through on delivering a more complete version quickly – incorporating early feedback as part of the iterative process of course! TOP

36. Is there a logical order to which parts of the FAQ to tackle first, and which to tackle right before we announce?

Strategy first, then execution details. Those details likely can only be locked down close to your launch. But by working out the answers to hard strategy questions early on, you can make the high-pressure days prior to announcement easier to manage. Your team will know what to say and why, and that can give them the confidence to press forward with marketing messages that they know are both management approved, and coherent. TOP

37. How do I publish our FAQ?

Since the FAQ is aimed primarily at developers who might want to collaborate, consider publishing it in the same place as the project’s other artifacts, such as the code repositories. For instance, if you’re putting the code up on GitHub, consider making the FAQ a single click away from the project’s README, and use GitHub Pages to publish. If you decide to publish it on your website as a linked HTML document, be sure to link to it from the code repositories as well, so developers can easily find it. In addition, you may choose to publish your FAQ as a PDF document that can be printed and left behind with customers or partners. TOP

38. What should the FAQ look like on our site? What works for navigating such a large document online?

A multi-level link architecture makes it easy for your readers to home in on the specific areas that interest them. At the top, you can include a table of contents of the major sections, with links to separate pages, or to locations within a single long HTML document. Each section can then have its own contents section with links to the individual questions in that section. Your site design team can create a navigation structure that fits with the architecture of your site, and that both makes it easy to zero in on specific information, and to browse and read whole sections or the entire FAQ to get the big picture. A few specific suggestions:

If you’re using a publishing platform such as GitHub Pages, just follow common conventions. There is no need to get fancy!
Number the questions. It is awkward to refer to “the 4th question on the licensing page” and much easier to refer to “question 43”.
Include an HTML anchor on each individual question so that readers can link to, bookmark, and reference specific questions.
Avoid the use of Flash and JavaScript code to dynamically reveal answers when you click on questions. This sort of slick eye candy makes it hard to link to a specific question and browse the whole FAQ, and won’t impress developers.
While it is a good idea to include a search box to let readers search for keywords, don’t rely on search as the only navigational aid for your FAQ. Make it easy to read and browse the FAQ as a complete document.

In the Resources section below, you’ll find links to example FAQs tailored toward developer audiences. As you’ll see, there are many ideas on how to make a complex, interlinked document like a FAQ easy to navigate. Keep it simple, minimize clicks and scrolling, and make it easy to know where you are in the document and follow tracks back to higher levels, and you’ll deliver a valuable resource to all of your audiences. TOP

39. How can I manage feedback on the FAQ and more questions as people read it and try to understand our platform initiative?

Perhaps the simplest way to manage feedback would be to include a contact button that is always available to someone reading the FAQ, that lets them directly submit their comments. Be sure that the inbox to where these comments are sent is staffed by someone empowered to track down and publish the answers to reader comments, including updates to the FAQ itself. The ultimate in transparency is to open your FAQ pages up for comments the way a blog includes comments. These comments can and should be moderated, but if you’re going to open your FAQ this way, you need to be scrupulous about publishing all comments both good and bad, as long as they are not spam. Otherwise, your community may begin posting their questions and comments elsewhere if they think you’re censoring their feedback. If your initiative is controversial, or very complex, a fully open comment system for your FAQ may be more transparency than is wise. If you can handle it though, such an open comment system is a powerful demonstration of transparency. TOP

40. We’re making a new announcement of changes to our community and platform efforts. Do I publish a new FAQ or edit the old one? How do I evolve my FAQ?

Your FAQ should be a living document. As your initiative changes, you can alter the FAQ to reflect new and different answers. That said, it helps developers to understand how things have changed, so you might include a Q&A right up front with the changes. And if the changes are not favorable to developers, you’ll need to be transparent in explaining them, and their rationale.

You should clearly label your FAQ with a version number and a date, so that readers can be certain of the version they are reading, and if they’ve printed or retained older versions they’ll know when you have published a revised version. TOP

41. How can I leverage the work on the FAQ for other marketing collateral?

The good news about spending so much time creating consistent, transparent messaging for your FAQ is that it can serve as a primary source for your other marketing materials. If your team uses standardized messaging guides, you can use the concepts and phrases you crafted for the FAQ to populate those messaging documents and marketing plans.

It may be tempting to turn this process upside down, and start by having your marketing team build a standard message guide and marketing plan, then use those to drive the writing of the FAQ. After all, the whole point of a message guide is to craft the messages independent of the particular collateral you’re creating, and use it to ensure consistency and motivate your marketing processes. This approach can lead to big problems, however. Usually, the marketing professionals who create messaging guides and drive the marketing process are the wrong people to create transparent messages for developers. By instinct and training, messaging experts often try to spin communications and paint the company in the best possible light, to hide unpleasant information, and to resist transparency in favor of a tightly controlled message focused on enhancing the brand. Just the opposite of what is needed in an effective FAQ.

That doesn’t make your marketing department bad, or incompetent – just ill-suited for this particular task. It is much better to develop the messaging by answering the hard questions truthfully, then use the resulting document in preparing your standard marketing materials through your normal processes. TOP

42. Does the FAQ have a role to play in PR and analyst outreach? How can I use the FAQ to further my marketing communications?

A well-crafted FAQ will likely answer nearly all of the questions that the press might have about your platform initiative. You can point reporters to appropriate Q&As if they submit written questions to you. You can also use the FAQ as a training document for your spokespeople. To make for more effective training, you might want to develop an abridged FAQ with only the most likely general-interest questions for the press and analysts. Spokespeople can study the answers to the most likely questions, while having the complete FAQ as a reference.

The FAQ also can be very helpful in developing executive communications material such as speaking guides and keynote presentations. By providing your leadership with great answers to hard questions, they will be ready for anything, and more likely to stay on message. Unfortunately, you may find that only the most detail-oriented executives will want to read the whole FAQ. This is the one situation where it might be a good idea to use an abridged FAQ for an internal employee audience. TOP

43. My organization isn’t ready to use this kind of FAQ for all these purposes. How do I help create the cultural changes needed internally for this approach to be embraced by my organization and its executives?

It can be hard to convince marketing, legal, and executive leadership that transparency is a good idea. These are often highly successful businesspeople who’ve delivered high-impact traditional marketing efforts with tight control, upbeat and one-sided messaging, and anything unpleasant out of sight. Some suggestions: try a small pilot project, and collect detailed feedback and conversations with developers as to how they use the FAQ and their impressions of it, and the project. Try to add outside advisors to your team who have experience and affinity with developers. The best advisors likely are the thought leaders for your external community. Exposing your leadership to these thought leaders may be a good way to bring their perspective to the fore. If these influential developers feel a part of your initiative, they’ll be much more likely to use their respected position in the community to help you with platform adoption.

There is no easy answer here. Your organization will need to learn these new skills, and may make mistakes. All the more reason to help that learning process through pilot projects where the stakes are lower, before trying to roll out your most important platform adoption initiatives! Patience and demonstrated success will, over time, change corporate culture to be more and more comfortable with transparency, when success or failure is more material to your organization’s goals. TOP

Resources

44. Can you point me to some good FAQs that illustrate these concepts and techniques?

Certainly! Here are a few:

Full disclosure – I wrote this one! OpenJDK (Java): http://icedtea.classpath.org/openjdk/java/faq.jsp.html
Eclipse: https://wiki.eclipse.org/The_Official_Eclipse_FAQs
Linux: http://www.tldp.org/FAQ/Linux-FAQ/intro.html
Android: https://source.android.com/setup/faqs
Python: https://docs.python.org/3/faq/general.html
GIMP: https://developer.gimp.org/faq.html
Creative Commons: https://creativecommons.org/faq/
Apache: https://www.apache.org/foundation/faq.html

TOP