UX Writing in Open Source Projects

UX writing is crucial in open source, as it helps users quickly grasp your message and intent

I have done a little research on this concept after doing some web dev work in open source since I want to expand my skills on it

Before you read

Three things every UX writer needs

• Creativity
• Problem-solving
• Empathy

UX writing is crucial for clear, user-friendly communication in digital products. It involves crafting concise, user-centered text that guides users through interfaces, much like note-taking for quick understanding. A key challenge is addressing the diverse user base, requiring inclusive writing that resonates with all. The question remains: How can better UX writing make open-source projects more inviting to both developers and users? To achieve this, UX writers can leverage various tools to enhance clarity and accessibility.

So What is my audience?

Short Answer: it depends
Long Answer: The audience comes from two main branches, non-technical users and technical users. Possible audience members include developers, designers, testers, or hobbyists who want to try something new. The main idea in figuring out the audience is to read what the product is about and be empathetic to address different writing levels.

I'd say at most keep it at 7th-grade level reading at most since it is the fastest and simplest to read

Main principles of UX writing

• Clarity: Avoid jargon and acronyms, and use straightforward language so it is easy to translate
• Accessibility: Ensure the writing is screen reader-friendly
• Neutrality: Use gender-neutral language and avoid culturally specific idioms
• Encouragement: Frame error messages and onboarding instructions positively, you always get positive feedback from positivity, even works when talking to AI - a skill in prompt engineering

Starting writing for open-source platforms (A summary of important files)

• ReadMe Files: Use headings and bulleted lists for easy navigation
• Documentation: Write step-by-step instructions assuming no prior knowledge with FAQs and troubleshooting sections
• Error Messages: Specify what the error is and avoid technical blame language
• Contribution Guidelines: Offer examples of well-written pull request descriptions or commit messages to set clear expectations for contributors

Encourage community collaboration

• provide helpful commit messages
• Add comments on the code so contributors can understand what it does and why the change was made

Overview of tools for UX writing

• Linter tools for documentation like Grammarly, Vale, or Write Good can help enforce clarity and tone consistency
• Style guides highlight key points like preferred terminology and tone

Real-world example

• Before: “Error: Invalid input”
• After: “Oops! We couldn’t process your input. Make sure it matches the format: YYYY-MM-DD”

List of tools

• For UX writing
  UX writing assistant: A plugin that integrates with Google Docs to ensure your writing aligns with UX best practices, such as tone and consistency
  Google UX Writing Playbook: Offers practical guidance and examples from Google's UX team

• For embedding UX writing
  Figma: Enables you to collaborate with designers and test microcopy in real-time
  Sketch: Great for learning how your words fit within interface components
  Adobe XD: Allows you to prototype designs and see how your copy works in a user interface

Subscriptions I recommend

• dailyuxwriting: for UX writing practice, since practice makes perfect

  I will write upcoming articles on this ^

• Growth.Design: Learn more about UX tools and case studies through fun comics

Conclusion

UX writing is an essential skill for making open-source projects more accessible and inviting. By focusing on clarity, accessibility, and community collaboration, UX writers can create user-friendly experiences that cater to diverse audiences. Whether it’s refining a README file, improving error messages, or designing inclusive documentation, thoughtful UX writing can make all the difference. Leverage the tools and principles discussed to enhance your contributions and create an inviting environment for both developers and users.