Key Takeaways

• Write in second person and active voice to ensure clarity.
  • Be declarative about what a developer can DO with Embrace
• Use sentence case for ALL headers
• Maintain a conversational, friendly, and concise tone.

1. Audience

• Primary audience: Mid-level mobile developers integrating our SDK.
• Reader’s background: Technical knowledge of mobile development, but not necessarily experts in advanced concepts.
• Implication: Write with moderate technical depth while maintaining clarity and approachability.

2. Tone & Voice

• Conversational, friendly, and respectful
  • Use a clear, approachable tone that feels human and helpful.
  • Avoid slang, jargon, clichés, or culturally specific references.
• Straightforward language
  • Be concise, direct, and mindful of a global readership with varying levels of English proficiency.
• Engaging yet polite
  • Strive for clarity and utility in instructions.
  • When asking users to do something, be polite but avoid repetitive use of “please.”
  • Example: “Add this line to your Podfile” instead of “Please add this line to your Podfile, thank you.”

3. Person & Voice

• Use second-person pronouns
  • Address the reader directly (e.g., “You can initialize the SDK,” instead of “We can initialize…”).
• Active voice
  • Clearly identify the actor: “You need to configure your app,” rather than “The app must be configured.”

4. Grammar, Mechanics & Terminology

• Conditions before instructions
  • “If you have not initialized the client, do that first” instead of “Initialize the client if you have not done so.”
• Terminology
  • Use consistent references to SDK elements. For example, always call it the “Embrace SDK” rather than mixing terms (like “the Embrace library” or “the Embrace kit”).
• Serial (Oxford) comma
  • Use commas before the final conjunction in a list (e.g., “install, configure, and run”).