Skip to content

Latest commit

 

History

History
33 lines (17 loc) · 2.88 KB

good-contribution.md

File metadata and controls

33 lines (17 loc) · 2.88 KB

What Makes a Good Contribution

We've collected a few ideas to help you understand what a good contribution looks like. First though, what does "good" mean, here? It means that the contribution is useful, easy to understand and assess, adds value, is focused on a single aspect, and -- to paraphrase Einstein -- "as small as possible but no smaller".

In addition to these ideas, you may also want to browse through existing pull requests that have the Merged status (see The Overall Process for more information on pull request statuses). These are pull requests that have been accepted and deemed useful, and looking at these examples will also give you more ideas.

A Well-Documented Pull Request

Convey your intentions clearly with a concise title and detailed explanation in your pull request.

Content contribution is not just about what you put in the changes that you include in your pull request. It's just as much about how you describe the change, in both the title and the body of the pull request.

Use the title to describe what the contribution is for, what it does. Use the body to describe what the contribution is, and why you're offering it. This helps the person processing your pull request enormously, and could make the difference between acceptance and rejection.

Focused Modifications

Make sure what you submit is limited to and focused only upon exactly what you want to change.

Sometimes, while making a modification, it's tempting to tweak and tune other parts of the content. For example, you might see that a couple of paragraphs nearby that would benefit from some extra whitespace between them. Avoid that temptation.

If you're making your contribution locally using an editor of your choice, that's great, but make sure it doesn't perform any automatic reformatting on save. This is because the modifications you submit will be more than you intend, and your commit will contain extraneous and irrelevant changes that could add confusion into the mix at review time.

After making your changes and saving them, check through the content of the commit(s) to ensure that there are no unintended modifications in there.

Limited to a Single Page

Limit your content contribution to a single SAP documentation page.

A change or addition across a number of different pages for a given topic is going to be more complex to describe and also implement, and is not an example of an ideal and simple contribution.

That's not to say that pull requests such as this will be ignored; sometimes content changes across multiple pages are required. But for those cases, it may be better to communicate that requirement via feedback, that is by raising an issue. Learn more about the types of contribution in Contributing to SAP Documentation.

A change or addition confined to a single page makes it easier to think about, assess and also more straightforward to merge.