7 |
8 | Permission is hereby granted, free of charge, to any person obtaining a copy
9 | of this software and associated documentation files (the "Software"), to deal
10 | in the Software without restriction, including without limitation the rights
11 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
12 | copies of the Software, and to permit persons to whom the Software is
13 | furnished to do so, subject to the following conditions:
14 |
15 | The above copyright notice and this permission notice shall be included in all
16 | copies or substantial portions of the Software.
17 |
18 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
21 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
23 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
24 | SOFTWARE.
25 |
--------------------------------------------------------------------------------
/goodies/templates/conduct.md:
--------------------------------------------------------------------------------
1 | # Contributor Code of Conduct
2 |
3 | As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
4 |
5 | We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality.
6 |
7 | Examples of unacceptable behavior by participants include:
8 |
9 | * The use of sexualized language or imagery
10 | * Personal attacks
11 | * Trolling or insulting/derogatory comments
12 | * Public or private harassment
13 | * Publishing other's private information, such as physical or electronic addresses, without explicit permission
14 | * Other unethical or unprofessional conduct.
15 |
16 | Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. By adopting this Code of Conduct, project maintainers commit themselves to fairly and consistently applying these principles to every aspect of managing this project. Project maintainers who do not follow or enforce the Code of Conduct may be permanently removed from the project team.
17 |
18 | This code of conduct applies both within project spaces and in public spaces when an individual is representing the project or its community in a direct capacity. Personal views, beliefs and values of individuals do not necessarily reflect those of the organisation or affiliated individuals and organisations.
19 |
20 | Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
21 |
22 | This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.2.0, available at [http://contributor-covenant.org/version/1/2/0/](http://contributor-covenant.org/version/1/2/0/)
23 |
--------------------------------------------------------------------------------
/join/about.md:
--------------------------------------------------------------------------------
1 |
2 | [Manifesto](https://github.com/the-whole-fruit/manifesto) | [ONE=MORTM](https://github.com/the-whole-fruit/manifesto/blob/master/goodies/one_more_framework.md) | [Templates](https://github.com/the-whole-fruit/manifesto/blob/master/goodies/templates) | [How to Adopt](https://github.com/the-whole-fruit/manifesto/blob/master/join/adopting.md) | [How to Sign](https://github.com/the-whole-fruit/manifesto/blob/master/join/signatories.md) | [How to Contribute](https://github.com/the-whole-fruit/manifesto/blob/master/.github/contributing.md) | [About](https://github.com/the-whole-fruit/manifesto/blob/master/join/about.md) | [License](https://github.com/the-whole-fruit/manifesto/blob/master/.github/license.md)
3 |
4 | # About
5 |
6 | **Why?** We’ve been in the software industry for more than a decade. And we've seen too many developers who, due to poor communication, either put a ceiling on their success or turn a wonderful piece of code into unusable trash. We've grown so frustrated with this, that we felt compelled to do something about it. We felt the urge to speak up and promote _the importance of good writing_ as part of a developer’s work. And we hope you’ll help us spread the word.
7 |
8 | **What's the plan?** To start a movement, baby! To make a dent in the developer’s world. To hammer in the idea that _words matter_ and that _it's not difficult_ to get decent at writing (definitely not more difficult than learning a new programming language). We want to see fewer and fewer projects that are _hurt_ by their communication. And long-term, we want to completely eliminate the stereotype that developers are bad at communication. In fact, we believe it could become the exact opposite. And we’re committed to build the tools to make that happen.
9 |
10 | **Who are we?** A [software developer](https://tabacitu.ro) and [a copywriter](https://ro.linkedin.com/in/andreiiordache). This is an unlikely alliance, we know. But it's probably the best mix for starting a project like this.
11 |
12 | **How can I learn more about writing effectively?** We are [writing a book](https://writingfordevs.com) for software developers. So, if a brief `contributing.md` section can get you from bad to decent, think what a book can do for you. While we work on the book, we’re going to share a lot of useful titbits, so [follow us on Twitter](https://twitter.com/writingfordevs) and be sure to [subscribe to our newsletter](https://writingfordevs.com/#download). Also, we would love to hear your ideas - just drop us a line at [contract@writingfordevs.com](mailto:contact@writingfordevs.com)
13 |
--------------------------------------------------------------------------------
/goodies/templates/contributing.md:
--------------------------------------------------------------------------------
1 | # Contributing
2 |
3 | Contributions are welcome and will be fully credited:
4 | - code contributions are accepted via Pull Requests to the [my-vendor/my-package]() repo;
5 | - financial contributions are usually in the form of [donations](), [license purchases](), [projects]() or [jobs]();
6 | - documentation contributions are accepted via Pull Requests to the [my-vendor/my-package]() repo;
7 | - other contributions are most likely welcome in the way you see fit;
8 |
9 | ## Things you could do
10 |
11 | If you want to contribute but do not know where to start, this list provides some starting points.
12 | - improve [our documentation]();
13 | - provide more examples;
14 | - review and test [existing PRs]();
15 | - review [bug reports]();
16 | - offer to code [approved feature requests]();
17 | - answer [support requests]();
18 |
19 | ## How to do those things
20 |
21 | ### Pull Requests
22 | - **Add tests!** - Your patch will be accepted MUCH faster if it has tests.
23 | - **Document any change in behaviour** - Make sure the `readme.md` and any other relevant documentation are kept up-to-date.
24 | - **Consider our release cycle** - We try to follow [SemVer v2.0.0](http://semver.org/). Randomly breaking public APIs is not an option.
25 | - **One pull request per feature** - If you want to do more than one thing, send multiple pull requests.
26 | - **Send coherent history** - Make sure each individual commit in your pull request is meaningful. If you had to make multiple intermediate commits while developing, please [squash them](http://www.git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages) before submitting.
27 |
28 | ### Issues
29 | - **Answer all items in the issue template** - It helps us resolve problems without a lot of back-and-forth.
30 | - **No support requests** - The maintainers and people who follow this project are all busy people. Please do not expect them to help you code something that will only work inside your project or debug an issue that is most likely your own doing.
31 |
32 | ### Rules for writing effectively
33 |
34 | This project stands by [The Whole Fruit Manifesto](https://github.com/the-whole-fruit/manifesto). We believe that “_writing good code_” is not _only_ about “_writing good code_”. It’s also about the words around it. That’s why, to make sure your contribution is well received, we ask you to [read and apply the ONE=MOR framework and guidelines](https://github.com/the-whole-fruit/manifesto) when writing comment blocks, PR titles, PR descriptions, and in general, when writing to our community.
35 |
36 |
37 | Happy coding!
38 |
--------------------------------------------------------------------------------
/.github/contributing.md:
--------------------------------------------------------------------------------
1 |
2 | [Manifesto](https://github.com/the-whole-fruit/manifesto) | [ONE=MORTM](https://github.com/the-whole-fruit/manifesto/blob/master/goodies/one_more_framework.md) | [Templates](https://github.com/the-whole-fruit/manifesto/blob/master/goodies/templates) | [How to Adopt](https://github.com/the-whole-fruit/manifesto/blob/master/join/adopting.md) | [How to Sign](https://github.com/the-whole-fruit/manifesto/blob/master/join/signatories.md) | [How to Contribute](https://github.com/the-whole-fruit/manifesto/blob/master/.github/contributing.md) | [About](https://github.com/the-whole-fruit/manifesto/blob/master/join/about.md) | [License](https://github.com/the-whole-fruit/manifesto/blob/master/.github/license.md)
3 |
4 | # Contributing
5 |
6 | Contributions are welcome and will be fully credited:
7 | - text contributions are accepted via Pull Requests to the [the-whole-fruit/manifesto](https://github.com/the-whole-fruit/manifesto) repo;
8 | - financial contributions are not needed;
9 |
10 | ## Things you could do
11 |
12 | If you want to contribute but do not know where to start, this list provides a starting point:
13 | - improve the manifesto, guidelines, everything - we don't claim to know it all;
14 | - improve our templates - they can get better with the experience of more people;
15 | - review and give your opinion on [existing issues](https://github.com/the-whole-fruit/manifesto/issues);
16 | - review and give your opinion on [existing pull requests](https://github.com/the-whole-fruit/manifesto/pulls);
17 | - [adopt the manifesto](https://github.com/the-whole-fruit/manifesto#how-to-adopt);
18 | - save a project - if you know a project that will benefit a lot by communicating better in writing tell them about The Whole Fruit Manifesto; it will do a lot of good to them, to you and to the world wide web;
19 | - spread the word - don't forget to give us a star on GitHub and share;
20 |
21 | ## How to do those things
22 |
23 | ### Pull Requests
24 | - There are no restrictions. Go ahead and submit your PR!
25 |
26 | ### Issues
27 | - There are no restrictions. Go ahead and submit your issue!
28 |
29 | ### Rules for writing effectively
30 |
31 | This project stands by [The Whole Fruit Manifesto](https://github.com/the-whole-fruit/manifesto). We believe that “_writing good code_” is not only about “_writing good code_”. It’s also about the words around it. That’s why, to make sure your contribution is well received, we ask you to [read and apply the ONE=MOR framework and guidelines](https://github.com/the-whole-fruit/manifesto) when writing comment blocks, PR titles, PR descriptions, and in general, when writing to our community.
32 |
33 |
34 | Thank you for contributing!
35 |
--------------------------------------------------------------------------------
/join/signatories.md:
--------------------------------------------------------------------------------
1 |
2 | [Manifesto](https://github.com/the-whole-fruit/manifesto) | [ONE=MORTM](https://github.com/the-whole-fruit/manifesto/blob/master/goodies/one_more_framework.md) | [Templates](https://github.com/the-whole-fruit/manifesto/blob/master/goodies/templates) | [How to Adopt](https://github.com/the-whole-fruit/manifesto/blob/master/join/adopting.md) | [How to Sign](https://github.com/the-whole-fruit/manifesto/blob/master/join/signatories.md) | [How to Contribute](https://github.com/the-whole-fruit/manifesto/blob/master/.github/contributing.md) | [About](https://github.com/the-whole-fruit/manifesto/blob/master/join/about.md) | [License](https://github.com/the-whole-fruit/manifesto/blob/master/.github/license.md)
3 |
4 | # Signatories
5 |
6 | We hereby declare that we recognize the importance of effective communication, and commit to doing better. We pledge to improve the way we write _inside_ and _around_ our projects. As part of this process, we will:
7 | - follow [The Whole Fruit Guidelines](https://github.com/the-whole-fruit/manifesto/blob/master/goodies/guidelines.md) as much as possible;
8 | - copy-paste or link to the [The Whole Fruit Manifesto](https://github.com/the-whole-fruit/manifesto), to motivate and teach our contributors to write better;
9 | - use the provided [markdown templates](https://github.com/the-whole-fruit/manifesto/tree/master/goodies/templates) (as-is or modified) to ensure our contributors communicate better too;
10 | - admit that you're never _done_ learning how to communicate, and be open to improvements;
11 | - help promote the manifesto with [a link](https://github.com/the-whole-fruit/manifesto), [a shield](https://github.com/the-whole-fruit/manifesto/blob/master/.github/contributing.md#include-a-shield-in-your-project), a star on Github or all of them;
12 |
13 |
14 | Signed,
15 |
16 |
17 | ## Projects & Organisations
18 |
19 | Date | Project / Organisation | About
20 | ------------ | ------------- | -------------
21 | 2020-09-15 | [Backpack for Laravel](https://backpackforlaravel.com) | The most popular admin panel for Laravel-PHP
22 | 2020-09-15 | [UPDIVISION](https://updivision.com) | Custom web & mobile apps: 10 years of oursourcing excellence
23 |
24 |
25 | ## People
26 |
27 | Date | Name | About
28 | ------------ | ------------- | -------------
29 | 2020-09-15 | [Cristian Tabacitu](https://www.linkedin.com/in/tabacitu/) | Indie Maker, leads [:DigitallyHappy](https://digitallyhappy.com)
30 | 2020-09-15 | [Andrei Iordache](https://www.linkedin.com/in/andreiiordache/) | CEO of [UPDIVISION](https://updivision.com), copywriter by trade and occupation
31 |
32 |
33 | -----
34 |
35 | To sign the manifesto, please submit a Pull Request with a new line for your project/organisation.
36 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 |
2 |
3 | 
4 |
5 | 
6 |
7 | 
8 |
9 | 
10 |
11 | 
13 |
14 |
15 | 
16 |
17 |
18 |
19 |
20 | An unspeakable evil plagues the world of software developers. It’s present in private software projects and in oh so many open source contributions. It prevents brilliant engineers making a name for themselves. And the coolest projects from taking off. That evil is poor communication in writing.
21 |
22 | Because **“_writing good code_” is not only about “_writing good code_”**.
23 |
24 | Sure, the code is the kernel. But around it, or about it, the software developer has to write a lot of words:
25 |
26 | - Technical Documentation
27 | - Code Comments
28 | - Commits, Pull Requests
29 | - Tasks
30 | - Emails and many more
31 |
32 | We believe that **good code can be made bad by improper use of words around it**. Therefore, a software developer who strives to deliver good code should also strive to communicate effectively in writing. Such is the whole fruit of a developer’s labor, kernel and all.
33 |
34 | **Our mission is to spread the good word. Will you join us?**
35 |
36 | 
37 |
38 | [ONE=MORTM](https://github.com/the-whole-fruit/manifesto/blob/master/goodies/one_more_framework.md) | [Templates](https://github.com/the-whole-fruit/manifesto/blob/master/goodies/templates) | [How to Adopt](https://github.com/the-whole-fruit/manifesto/blob/master/join/adopting.md) | [How to Contribute](https://github.com/the-whole-fruit/manifesto/blob/master/.github/contributing.md) | [About](https://github.com/the-whole-fruit/manifesto/blob/master/join/about.md) | [License](https://github.com/the-whole-fruit/manifesto/blob/master/.github/license.md)
39 |
--------------------------------------------------------------------------------
/join/adopting.md:
--------------------------------------------------------------------------------
1 |
2 | [Manifesto](https://github.com/the-whole-fruit/manifesto) | [ONE=MORTM](https://github.com/the-whole-fruit/manifesto/blob/master/goodies/one_more_framework.md) | [Templates](https://github.com/the-whole-fruit/manifesto/blob/master/goodies/templates) | [How to Adopt](https://github.com/the-whole-fruit/manifesto/blob/master/join/adopting.md) | [How to Sign](https://github.com/the-whole-fruit/manifesto/blob/master/join/signatories.md) | [How to Contribute](https://github.com/the-whole-fruit/manifesto/blob/master/.github/contributing.md) | [About](https://github.com/the-whole-fruit/manifesto/blob/master/join/about.md) | [License](https://github.com/the-whole-fruit/manifesto/blob/master/.github/license.md)
3 |
4 | # How to Adopt
5 |
6 | ## Step 1. Add a The Whole Fruit Manifesto & Guidelines to your `CONTRIBUTING.md`
7 |
8 | > One small block of text to add to your CONTRIBUTING.md file, one giant leap in software quality for your project.
9 |
10 | Github, Bitbucket and Gitlab use this file to show developers a few guidelines before they submit a PR. We think it's a perfect place to also talk about the guidelines your community follows when communicating in writing. If you adhere to The Whole Fruit Manifesto feel free to copy or link directly to its Writing Guideline. If you don’t have any idea how to structure your `CONTRIBUTING.md` file [here is a template](https://github.com/the-whole-fruit/manifesto/blob/master/.github/CONTRIBUTING.md) that we think is a good start.
11 |
12 |
13 | ## Step 2. Include a shield in your project
14 |
15 | Shields (aka badges) usually let people know about your project status, standards and permissions. So it's a perfect way to communicate that your project abides by The Whole Fruit Manifesto. You can easily add our shield to your `README.md`:
16 |
17 | [](https://github.com/the-whole-fruit/manifesto)
18 |
19 | ```js
20 | // use this at the top of your README.md file
21 |
22 | [](https://github.com/the-whole-fruit/manifesto)
23 |
24 | // or this
25 |
26 |
27 | ```
28 |
29 | Alternatively, you can use [shields.io](https://shields.io) to create a shield that's a better fit for your project. Make sure you point it to `https://github.com/the-whole-fruit/manifesto`
30 |
31 | ## Step 3. Sign the manifesto
32 |
33 | If you're the owner of an open-source project or organisation, you can [add your name to our `SIGNATORIES.md` file](https://github.com/the-whole-fruit/manifesto/blob/master/join/signatories.md). This will:
34 | - help you _publicly_ commit to follow The Whole Fruit Manifesto standard in your software projects;
35 | - help other people understand the importance of our cause: _better writing makes for better software_;
36 |
37 | 
38 |
39 | ## Step 4. Spread the word, save a project
40 |
41 | We bet you know a private or open source project that makes you cry everytime you read something they wrote. We all do! And now you can do something about it. Suggest that they check out The Whole Fruit Manifesto. It will do a lot of good to them, to you and to the world wide web.
42 |
43 | And, of course, don't forget to give us a star on GitHub and share.
44 |
--------------------------------------------------------------------------------
/goodies/one_more_framework.md:
--------------------------------------------------------------------------------
1 |
2 | [Manifesto](https://github.com/the-whole-fruit/manifesto) | [ONE=MORTM](https://github.com/the-whole-fruit/manifesto/blob/master/goodies/one_more_framework.md) | [Templates](https://github.com/the-whole-fruit/manifesto/blob/master/goodies/templates) | [How to Adopt](https://github.com/the-whole-fruit/manifesto/blob/master/join/adopting.md) | [How to Sign](https://github.com/the-whole-fruit/manifesto/blob/master/join/signatories.md) | [How to Contribute](https://github.com/the-whole-fruit/manifesto/blob/master/.github/contributing.md) | [About](https://github.com/the-whole-fruit/manifesto/blob/master/join/about.md) | [License](https://github.com/the-whole-fruit/manifesto/blob/master/.github/license.md)
3 |
4 | # Guidelines for Writing Effectively
5 |
6 | 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`.
7 |
8 | We believe that even reading this section _just once_ will result in better contributions and better communication.
9 |
10 |
11 | 
12 |
13 | ## Step 1. ORGANIZE the information to fit your goals and readers (the result is your _blueprint_)
14 | - **Mob** - know your readers
15 | - The readers of your PR are software developers, just like you. What compels them to read your PR?
16 | - 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.
17 | - 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.
18 | - 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.
19 | - **Mission** - determine your objectives
20 | - To get your PR approved. From the first try, if possible.
21 | - To lend a helping hand to someone who’s already helped you, by creating and maintaining a project.
22 | - **Message** - find what will make your readers act for your mission
23 | - In order for the maintainers to merge your PR, they’ll need to:
24 | - Easily understand what problem you’re fixing.
25 | - Agree that the problem is worth fixing.
26 | - Easily merge your work into the existing code base.
27 | - Most of the time, the message that should come across is that:
28 | - Your code contributes something important.
29 | - Your code is easy to read and well-commented.
30 | - Your code works and is well-tested.
31 | - **Medium** - select the best communication channel to use
32 | - For small contributions, go ahead and create a PR.
33 | - 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.
34 | - **Mood** - think about the tone that will make your message more convincing
35 | - Try to be informal, but not impolite. You’re talking to a colleague.
36 | - Jokes are welcome and appreciated. Especially good ones.
37 | - But most importantly, be direct. You are improving something specific.
38 | - Bonus tip: One or two emojis or GIFs can easily lighten the mood.
39 | - **Mould** - Decide the structure that will carry your message home
40 | - 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.
41 | - If there’s no Issue template, here’s [a good structure for a Bug Report](https://github.com/the-whole-fruit/manifesto/blob/master/.github/ISSUE_TEMPLATE/bug_report.md).
42 | - If there’s no PR template, here’s [a good structure for a PR description](https://github.com/the-whole-fruit/manifesto/blob/master/.github/ISSUE_TEMPLATE/pull_request.md).
43 |
44 | ## Step 2. NOTE everything down following the blueprint (the result is your _first draft_)
45 | - Only clear Subjects
46 | - [ ] Sentences start with their subject (X did Y);
47 | - [ ] One sentence, one subject;
48 | - [ ] The subject is a person or a concrete object;
49 | - [ ] The subject is clear (if unclear, properly explain the subject and its role);
50 | - 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_.
51 | - Only clear Actions
52 | - [ ] The action is concrete and easy to understand;
53 | - [ ] The action comes right after the subject (X did Y);
54 | - [ ] Use verbs instead of subjects whenever possible;
55 | - 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"_;
56 | - Only the right Style
57 | - [ ] Use the same words you would if you were speaking them;
58 | - [ ] Use simple words, that anybody can understand;
59 | - [ ] Avoid abstract words. Avoid buzzwords.
60 | - [ ] Write about what can be experienced, felt.
61 | - [ ] Be direct and concrete.
62 | - [ ] Use examples, metaphors or comparisons where complicated.
63 | - [ ] Avoid passive voice.
64 | - [ ] Use the right words for the amount of certainty you have about the subject at hand.
65 | - [ ] Avoid jargon.
66 | - [ ] Use bullet points instead of enumerations.
67 | - [ ] Highlight/underline/bolden the key ideas or words.
68 | - [ ] Explain the acronyms/abbreviations if any.
69 | - [ ] Make sure the text is easy to read and has a good flow.
70 | - Only the right Length
71 | - [ ] Keep the message as short as possible, without missing crucial information.
72 | - [ ] At most, sentences should have 20-25 words each.
73 | - [ ] Break down long sentences into short ones - one idea per sentence.
74 | - [ ] Alternate long sentences with short ones.
75 |
76 | ## Step 3. EDIT it to make sure it does what it needs to do (the result is your _final text_)
77 | - Read once for sense and structure (the result is your _second draft_)
78 | - Read once to make sure it sounds good (the result is your _third draft_)
79 | - Read once for grammar (the result is your _final draft_)
80 |
--------------------------------------------------------------------------------
