Skip to content

Latest commit

 

History

History
79 lines (70 loc) · 6.68 KB

one_more_framework.md

File metadata and controls

79 lines (70 loc) · 6.68 KB

Manifesto | ONE=MORTM | Templates | How to Adopt | How to Sign | How to Contribute | About | License

Guidelines for Writing Effectively

The ONE = MOR framework was created to help software developers communicate better in writing. So feel free to link to this section in your Contributing.md.

We believe that even reading this section just once will result in better contributions and better communication.

Step 1. ORGANIZE the information to fit your goals and readers (the result is your blueprint)

  • Mob - know your readers
    • The readers of your PR are software developers, just like you. What compels them to read your PR?
      • If you’re contributing to an open source project, they’ve probably put in hundreds or thousands of hours of their life into a project that makes no money, or very little money. Most likely they are busy, have full-time jobs, spouses, children, pets. But, just like you, they have a passion for building stuff, and they love that their work actually helps people.
      • If you're contributing to your company’s project, then the developer who reviews the PR has to do it because it’s her job.
      • Either way, you want to make their life as easy as possible and the task as pleasant as possible. Don’t treat them like they don’t have a choice but to review your code. Because, just like you, they have a passion for building stuff, and they love that their work actually helps people. That's why they started this. That's why they keep doing it.
  • Mission - determine your objectives
    • To get your PR approved. From the first try, if possible.
    • To lend a helping hand to someone who’s already helped you, by creating and maintaining a project.
  • Message - find what will make your readers act for your mission
    • In order for the maintainers to merge your PR, they’ll need to:
      • Easily understand what problem you’re fixing.
      • Agree that the problem is worth fixing.
      • Easily merge your work into the existing code base.
    • Most of the time, the message that should come across is that:
      • Your code contributes something important.
      • Your code is easy to read and well-commented.
      • Your code works and is well-tested.
  • Medium - select the best communication channel to use
    • For small contributions, go ahead and create a PR.
    • For bigger contributions, it’s better to create an Issue first, to make sure the problem you discovered is worth working on; don’t start working, before you know your work will be merged.
  • Mood - think about the tone that will make your message more convincing
    • Try to be informal, but not impolite. You’re talking to a colleague.
    • Jokes are welcome and appreciated. Especially good ones.
    • But most importantly, be direct. You are improving something specific.
    • Bonus tip: One or two emojis or GIFs can easily lighten the mood.
  • Mould - Decide the structure that will carry your message home
    • The Issue or PR you’re opening should already include some text and headlines, to make sure your message is well structured. Try to answer all existing headlines. If needed, add new headlines, but don’t delete the existing ones, they’re there for a reason.
    • If there’s no Issue template, here’s a good structure for a Bug Report.
    • If there’s no PR template, here’s a good structure for a PR description.

Step 2. NOTE everything down following the blueprint (the result is your first draft)

  • Only clear Subjects
    • Sentences start with their subject (X did Y);
    • One sentence, one subject;
    • The subject is a person or a concrete object;
    • The subject is clear (if unclear, properly explain the subject and its role);
    • For example: Rather than saying "404 error on moderation", you should say something like "When the users click the Moderate button they get a 404 Error." - when the subject is a person, it reads like a story - which is good; When the subject is the first thing in the sentence, you set a clear context.
  • Only clear Actions
    • The action is concrete and easy to understand;
    • The action comes right after the subject (X did Y);
    • Use verbs instead of subjects whenever possible;
    • For example: "Authentication throws error 500 when token is missing" is more difficult to understand than "User tries to authenticate without a token, but sees a 500 error page";
  • Only the right Style
    • Use the same words you would if you were speaking them;
    • Use simple words, that anybody can understand;
    • Avoid abstract words. Avoid buzzwords.
    • Write about what can be experienced, felt.
    • Be direct and concrete.
    • Use examples, metaphors or comparisons where complicated.
    • Avoid passive voice.
    • Use the right words for the amount of certainty you have about the subject at hand.
    • Avoid jargon.
    • Use bullet points instead of enumerations.
    • Highlight/underline/bolden the key ideas or words.
    • Explain the acronyms/abbreviations if any.
    • Make sure the text is easy to read and has a good flow.
  • Only the right Length
    • Keep the message as short as possible, without missing crucial information.
    • At most, sentences should have 20-25 words each.
    • Break down long sentences into short ones - one idea per sentence.
    • Alternate long sentences with short ones.

Step 3. EDIT it to make sure it does what it needs to do (the result is your final text)

  • Read once for sense and structure (the result is your second draft)
  • Read once to make sure it sounds good (the result is your third draft)
  • Read once for grammar (the result is your final draft)