Many developers face the same challenge when contributing to GitHub for the first time: the code works perfectly, but when writing a README, submitting an Issue, or creating a PR in English, it never feels quite right. You worry that others might not understand what you mean.
This concern is completely normal. Technical English is different from everyday English—it has its own conventions and common phrases. The good news is that once you grasp a few basic patterns, writing these documents is much easier than you might think.
README: Help Others Quickly Understand Your Project
A README is the first window through which others see your project. A clear README usually organizes information in the following order: explain what the project does, show how to use it, and provide any additional helpful information.
The project description should be straightforward. For example, "This project helps you manage your daily tasks more efficiently" is better than "This is an awesome task management tool." The former clearly explains the purpose, while the latter is just self-praise.
Next, installation and usage instructions are crucial. Write them from the perspective of someone who knows nothing about your project. Each step should be clear and precise—don’t skip any seemingly “obvious” steps. For example, when installing dependencies, you could write, "Install dependencies by running npm install," rather than just "Install dependencies."
Code examples are equally important. A good example should be complete and runnable, without requiring the reader to guess missing parts. For instance, when demonstrating an API call, include import statements, initialization, and the actual call.
Issue: Describe Problems and Requests Accurately
When writing an Issue, the most important thing is to let maintainers quickly understand the problem or feature request. A common mistake is being too brief, e.g., just writing, "It doesn't work." Such descriptions are not helpful.
When reporting a bug, organize information in a "symptom–expected behavior–environment" order. First, describe the issue you observed, then state what you expected, and finally provide your environment details. For example:
"When I click the submit button, the page shows a 500 error. I expected the form to be submitted successfully. I'm using Chrome 91 on macOS 12.1."
If possible, provide a minimal reproducible example. This helps maintainers quickly locate the issue and shows that you’ve spent time investigating it.
When requesting a new feature, explain why you need it rather than just stating what you want. For example:
"I often need to batch delete multiple items, but currently I have to delete them one by one, which is time-consuming"
is much better than
"Please add batch delete feature."
PR: Clearly Explain Your Changes
A Pull Request is the formal way to contribute code, so your description needs extra care. A good PR description should make reviewers understand three things: what you changed, why you changed it, and whether the change is safe.
The title should be concise yet informative. "Fix user login bug" is better than "Bug fix," and "Add email validation to user registration" is better than "Update user.js." The title should clearly convey the main purpose of the PR.
In the body, start with context. What problem prompted this change? If fixing a bug, briefly describe its behavior; if adding a feature, explain the use case. Then detail your solution, and if you considered multiple approaches, mention why you chose the current one.
Testing information is also important. Explain how you verified your changes. For example:
"I tested this change by creating a new user with an invalid email address and confirmed that the validation error is properly displayed."
Make Your English More Natural
There are a few tips to make your English writing more fluent.
First, pay attention to tense. Use the present tense for current behavior, e.g., "This function returns the user's email"; past tense for changes you made, e.g., "I added validation for the email field"; and future tense or modal verbs for expected effects, e.g., "This change will prevent invalid emails" or "Users should no longer see the error message."
Second, mind the tone. In open-source environments like GitHub, polite but direct is best. You don’t need to be overly apologetic (e.g., "I'm sorry to bother you, but..."), but also avoid sounding too harsh. "Could you help me understand why..." is better than "I don't understand why..."
Finally, use common phrases. For example:
- To describe a problem: "I'm experiencing an issue where..."
- To ask for help: "I would appreciate any guidance on..."
- To explain changes: "This PR addresses the issue by..."
Using these phrases repeatedly will make them habitual. Eventually, you’ll naturally write clear, precise technical documents. Remember, perfect English isn’t the goal—the key is making your ideas understandable to others.
Top comments (0)