Home / GitHub Page

Upon Laurent's Request, Let's Discuss Improving Documentation and Styling Guidelines To Help New and Old Contributors

I started a PR revolving around improving the Documentation for this project, and @laurent suggested that the issue be discussed here on the forums.

What kind of information would be useful for contributors? Can you all suggest some possible templates for documentation?

I know that off the top of my head, one very important thing to consider when contributing is to make sure all linter plugins are completely disabled in your editor of choice so that they don’t interfere with eslint. I found out first hand that that can happen pretty easily.

1 Like

Create initiative, thanks for helping out here.
I hope to find some minutes to drop some thoughts

1 Like

during the application preparation process I collect some reference for improving the documentation.
You can split them in three groups

  1. code structure

    1. I wouldn’t mind if we start do create a graph on draw.io to visualize it nicely. Mattermost is a good example: https://docs.mattermost.com/overview/architecture.html
  2. how to code:

    1. tell what IDE etc. to use. You don’t have to explain it, a numbered steps list, referencing to the relevant doc section would be sufficient. We all know that reading through all the docs isn’t fun, e.g. recent case GSoC2020- Intoduction to community.
      That could be tackled by saying:

      1. get React Native as explained in
      2. apply these settings
      3. get a simulator as explained here

      or in case git

      1. get git CL version, other tools with GUI we can recommend are … but we won’t support for technical question
      2. do clone, pull etc. as described in …

      some suggestion might be obviously, some might “if you want to code, you should know that” but in the end is all about lowering the entry barrier!
      Discourse doing it quite well: https://meta.discourse.org/t/discourse-development-contribution-guidelines/3823

  3. Contribution Guidelines

    1. an example with a lot of text, rather generic: https://zulip.readthedocs.io/en/latest/contributing/version-control.html#commit-discipline

    2. same here but review and additional resources section is good read:
      https://zulip.readthedocs.io/en/latest/contributing/code-reviewing.html#additional-resources
      A real pearl is their tool collection for visualizing the benefit of a PR:
      https://zulip.readthedocs.io/en/latest/tutorials/screenshot-and-gif-software.html
      Moreover they put a lot of effort visualizing the coding style:
      https://zulip.readthedocs.io/en/latest/contributing/code-style.html

    3. same for rocket.chat:
      https://github.com/RocketChat/docs/tree/master/developer-guides/code-styleguide/less

    4. and nextcloud:
      https://docs.nextcloud.com/server/latest/developer_manual/general/codingguidelines.html

have look what was criticized in the GSoC realted PRs: https://github.com/laurent22/joplin/pulls?utf8=✓&q=is%3Apr+label%3Agsoc-2020+

my idea is to apply for GSoC to get that done/supported by a student.
As many docs are on readthedocs.io what integrate nicely wiht GitHub Joplin doc may moves there as well.

@antreev-brar @sarthakpranesh @amitsin6h @rheo may you want to share your recent experience with Joplin coding and tell how things could go more smoothly

so what do you think to much at once :slight_smile:

I’m sorry but i have no clue what this statement means. Ha.

I also wanted to get this discussion going but you sound like you have some pretty solud ideas there, @PackElend. i recently came to the personal realization that I’m a natural control freak and want to change that so i can be a better person overall. @laurent, if anyone should work on this feature, i vote Pack here to head it.

Although, i will say editor / ide of choice shouldn’t be hard set as much as making sure that any linters are disabled. I found out first hand that eslint doesn’t play nice with any other linters and can have adverse effects with the current rules setup.

Hello @PackElend, I’m trying to understand what you’re saying here, but if it’s about revamping the documentation, then count me in. I do a lot of writing and I enjoy documenting code, I also have a PR on Improving the Docs in Joplin which was successfully merged, so I will be very glad to add this to my GSOC goals

1 Like

Hi guys,

How are you?

I stumbled upon Joplin about a week ago and have used it since. Currently really busy combining work and university, so it comes in handy. I just read this post on the forum and thought maybe we can help each other out.

Let me explain:

I am a postgraduate student at VU University Amsterdam (Netherlands), currently following a course called “Digital Innovation & Virtual Organizing in a Global Setting”. We’re currently learning about open source development teams, in particular ways of working and coordination within these type of teams.

For an assignment, me and my group members are to pick a project, and find a way we can contribute by combining our theoretical knowledge and information we gather from having a chat with a couple of contributors.

How do you guys feel about this? We can’t code and do not know much about coding, but we might be able to help with something else, like creating a guideline template. We could also give some advice in terms of coordination and ways of working, and you’ll be able to add the more detailed coding-guidelines.

Of course, we’re also down to contribute in any other way, for example conducting some research in regard to user behaviour, trends in the market, a small survey at our uni etc. etc. You name it!
The only point of criteria is that it has to be feasible in a relatively small amount of time, because we’ve only been given about 1,5 week to write a report.

Would love to explain the idea a bit further and hear your opinions on this by having a quick chat with a couple of you.

Thanks!

Daniëlle Schultz
& the rest of my team

2 Likes

I am working with the recent codebase only these seems to be a bit more clear but what I see as the problem is the choice of the library we have used in the Joplin app for the ReactNativeClient project and the reason why I believe sometimes the android app works slow.

Instead of react-native-popup-dialog we can use react-native-modalbox it is fast.
Can we also update the react-navigation version, this will also improve the performance.

Also, let me know if I can help with updating the documentation.
The first time when I started with Joplin while setting up the development environment, document had some problem and suggest the changes.

2 Likes

that is my suggestion, using readthedocs.io
@danielleschultz you are more than welcome here to help us to make it an easy start.
The target should be to allow folks you and me to set up the proper IDE and repeat a PR easily

Wait for @laurent and @tessus for feedback

needs some feedback from @laurent

I pull in the latest contributor @marijawo as he should aware of this too.

there are surveys ongoing here:

summarizing these could be a good start

@amitsin6h, there are lots of things that can be improved on the mobile app, but changing components that work fine is very low priority.

2 Likes

@danielleschultz, that could be interesting but it’s not entirely clear to me what your project would be about? Perhaps if you could describe a concrete example - what the project will be about, what will be the process, etc.

Thanks for your reply @laurent. It is basically a mini-research project.

The purpose is to analyze a distributed team and identifying coordination practices. The aim is to learn more about your ways of coordinating by comparing it to what we learn in the theory of coordination of distributed work.

Based on our analysis and by chatting to you, we want to find a way in which we can contribute to the project, based on our skills. It’s about trying to find a way to help out while gaining some hands-on experience. So this could be a small market research, analysis about the viability of the product, a user experience test, or by writing an advisory report in regard to coordination, which could include certain guidelines, templates, etc.

If you have some ideas or any kind of thing you have been wanting to research/do for a while, but have not found the time or the right person, then we can perhaps give it a shot.

If you want I can send you the assignment guide?
It would mean a lot. We would love to help out!

Daniëlle
d.schultz@student.vu.nl

1 Like

If Joplin get accepted for GSoC we will enter new lands in regard to communication anyway :slight_smile: as there is strict timeline.

1 Like

Hi @laurent!
Would love to hear what you think of my post above.

Thanks.

@danielleschultz, you mentioned “small market research, analysis about the viability of the product, a user experience test” and all that would be useful to the project, with a preference for user experience test.

I think the biggest UX issue at the moment is the mobile app so if a user experience study could be done on it, it would help us identify what parts of it could be improved and how. That’s just an idea, assuming it would fit within the scope of your mini-project.

Market research I guess would also help us prioritise development work.

1 Like

I 100% agree with that. The mobile app is the source of most of my UX frustrations and probably other people are feeling the same.

@danielleschultz, with other multiplatform apps such as this, I’ve noticed many developers create different looks and feels for both Android and iOS devices. I’m assuming that’s due to how both platforms have their own different feels to their interfaces and those devs are trying to make the app feel like it belongs there. Do you have any ideas on this?

@Runo-saduwa, what kind of documentation are you wanting to contribute? As posted here and linked above by Pack, ReadTheDocs.io is a thing and, now that Joplin is officially a part of GSoC for 2020, let’s get this figured out and get going with it ASAP. :smiley:

@bedwardly-down thanks for filling me in,
Well, like I said earlier, I love to write and organize things, so I can contribute to any part of the documentation to make it great

I’ll also need to readthedocs.io to understand how it’s used, if you have a plan, please go ahead and We’ll take it from there