Contributing.md suggestions

Lounge
1

Some suggestions for Contributing.md:

  • User Support section should add "problems with installation" to list of topics that go in the forums. It should also make it more clear that user support goes in the forums, bugs go in github (but I don't know how to phrase that)

  • It needs something about "user support is handled by the community" and "you can help us by also helping users in the forums".

  • Some rules that should be added, but don't know how to phrase them:

    • Try to limit issues reports to 1 single issue per post.
    • Consider that enhancements should benefit a large portion of users (avoid suggesting features that only benefit your own weird specific workflow)
    • Long lists of "suggestions to improve Joplin" should go in the forums first.
    • Stay on topic (some issues start with one topic then the author starts reporting different issues)

  • Add a call for translators to keep translations up to date.

  • Add a list of 4 issues that you consider either easy for new users to start contributing, or essential for someone else to implement

  • Can you add some sort of priorities list like "In order of priority, we're focusing on the following: sync issues, android, ui, etc, etc". A roadmap is better but it seems you stopped doing that? A priority list informs users that their issue might not be implemented, and gives a starting point for those wanting to help.

Also:

  • The placeholder text when reporting an issue should repeat this line at the top:

Please read the guide first! joplin/CONTRIBUTING.md at master · laurent22/joplin · GitHub

A lot of people don't read instructions anyway, but this might help a little if it's the first thing they see.

  • Alternatively, add a pinned post on github with title "PLEASE READ BEFORE REPORTING AN ISSUE" linking to the Contributing page.
2

I like the idea. I was thinking about this myself, but never got around to it.

Are you referring to a new CONTRIBUTING.md file or an issue template? Github also allows to use different templates for bug reports and feature requests.

If Laurent gives the ok, why don’t you start and we can improve upon it (if even necessary - your suggestions look already pretty good).

3

I was referring to edits to the existing Contributing.md, and the "placeholder" text is for the template when reporting a bug.

Let's see what Laurent says. I can help, but english isn't my first language so always a bit afraid of writing official docs :slight_smile: and as you've seen I'm verbose and the docs shouldn't be something people don't want to read :joy:

4

No worries. Just start writing and we’ll do the rest. We all need proof-reading. I don’t use a spell-checker ever thus errors due to sticky keys (or sticky fingers) can happen once in a while.
Being verbose is not necessarily a bad thing. For text in CONTRIBUTING.md verbose is good.

In the bug report template the text should be concise. We also should create a template for feature requests. Let’s see what Laurent says.

5

I’m fine with improving Contributing.md and I think there’s some good ideas in what you suggest.

We need to keep concise of course since as you said a lot of people don’t read the instructions, but even if they do they might just skim through it. I guess we should somehow highlight the points that really matter to us and provide a bit more details for those who want to know more.

Not sure how to highlight these points though, maybe some kind of TLDR in each section or at the top of the file?

1 Like
6

Putting a 'tl;dr' at the top of a file just seems like a good way to make sure nobody ever reads the rest of it. :upside_down_face:

7

ok, I have a proposal for an updated Contributing.md here. What do you think about it?
I created a Gist for now as I'm guessing there'll be revisions.

for more detailed docs, maybe either open the wiki feature in github so that users can organize that on their own, or add new pages to the website for each topic, although more pages will also make it harder to keep things updated.

These are other "Contribute" pages I found useful for inspiration:

1 Like
8

Looks good to me. Could you create pull request with it so that we can see the diff?

Only issues I see are these:

  • Avoid suggesting enhancements/features that benefit a small portion of Joplin's users.

I think we can remove this because often we don't know who it will be useful for. Also sometimes if it's a small change for us, but it makes a big difference in some use cases, we might implement it. An example was the recent addition of the Markdown soft-break option, which is probably rarely used, but can be very useful to import Markdown notes with hard-coded line breaks.

  • Avoid reporting multiple issues in one report. One issue per report makes it easier to track and discuss it.

Not sure if it's often a problem in bug reports. Rather I'd move this to the "Feature request" section. Users often make multiple related suggestion in requests, which means they end up getting closed when one of the feature is done, but not all of them (or vice versa, they are never closed because one of the sub-feature hasn't been done yet).

9

I created a PR. I modified it based on your suggestions, too.

10
  • Add a style guideline for how new functions, properties and variables are to be written and named to help allow for the code to be consistent across the board. Then strictly adhere to those guidelines.