Let's Discuss Improving Documentation and Styling Guidelines To Help New and Old Contributors

bedwardly-down · 2020-02-21T23:06:22.270Z

Here’s my thoughts so far:

If you want all contributors to use the same tools and whatnot, you’ll need to settle for Visual Studio Code or something similar. There aren’t really any cross platform IDEs for React and Javascript that are universal to all major platforms, so my recommendation is the next best thing. It also would require Arch and Gentoo users to either downgrade their kernel to 5.4 or change Linux distributions altogether due to multiple bugs that are predominantly on rolling release distributions due to their bleeding edge nature. And these bugs are primarily related to Electron and Chromium.

OBS-Studio is a great option for screen recording for those that want to show their tests in real time and use video / gif as their proof of fix. It works extremely well across all platforms.

Each platform has their own apps for taking screenshots of the desktop and apps that are being run / tested. Scrot is a great command line tool for Linux. Screengrab is one of the better gui based ones that has support for a variety of resolutions and compression types. It’s also a default app in many desktop environments.

Some projects require github contributions to be made by users that use their real names and have some kind of identifying information (like a portfolio or resume attached to their accounts) to allow the devs to verify that they are qualified to work on the project. This is something that would be important to decide on and add to the documentation.

There should be set rules and guidelines for how tests should be performed and those that don’t show valid results (like my video example above), their bug reports and fixes should not be accepted.

Minimum requirements of tool knowledge to be able to contribute and / or test Joplin.

PackElend · 2020-02-22T08:32:52.345Z

bedwardly-down:

Some projects require github contributions to be made by users that use their real names and have some kind of identifying information (like a portfolio or resume attached to their accounts) to allow the devs to verify that they are qualified to work on the project. This is something that would be important to decide on and add to the documentation.

I expect that to be in the proposal:

About me

Provide your contact information (IRC nick, email, IM, phone) and write a few sentences about you and why you think you are the best for this job. Prior contributions to Joplin are required; list your commits. Name people (other developers, students, professors) who can act as a reference for you. Mention your field of study if necessary. Now is the time to join the relevant irc/telegram channels, mail lists and blog feeds. We want you to be a part of our community, not just contribute your code.

Tell us if you are submitting proposals to other organizations, and whether or not you would choose Joplin if given the choice.

Is that enough?

bedwardly-down · 2020-02-22T14:54:03.541Z

I hadn’t checked into that document. Thanks. I was meaning for the general project and not specifically GSoC. And you asked for general places to start and i was just saying what was off the top of my head in that moment. Ha

PackElend · 2020-02-22T15:00:48.798Z

bedwardly-down:

I was meaning for the general project and not specifically GSoC

same idea here, but GSoC is the most urgent currently

bedwardly-down · 2020-02-22T15:05:52.016Z

Most definitely. Could GSoC be kind of a test bed for how the rest of the project will go in the future if things go well with that?

PackElend · 2020-02-22T15:13:25.644Z

I would say the entire GSoC thing is test bed for us in many regards

bedwardly-down · 2020-02-22T15:16:28.776Z

Count me in. I am ready to see what happens. Ha

PackElend · 2020-02-24T19:28:17.945Z

I’m starting with giving GSoC 2020 live blog structure.
I’ll continue collecting. As soon as I have significant additional amount of bullet points for contribute, built and troublehshooting, I’ll derive readthedocs from it

bedwardly-down · 2020-02-24T22:08:10.813Z

I disagree with telling people to Google before needing help with an issue only because not everyone knows where to properly look for help or what exactly the kind of help they’ll need is. Many times, Google searches will take people to stack overflow and other forum posts that may not necessarily offer what they’re looking for or offer the wrong information. Here’s my suggestions on two good resources for possibly common questions.

Reactjs: https://reactjs.org/
Electron issue tracker (if working on Desktop client and running into unusual behavior): https://github.com/electron/electron/issues

PackElend · 2020-02-25T09:39:28.973Z

bedwardly-down:

I disagree with telling people to Google before needing help with an issue only because not everyone knows where to properly look for help or what exactly the kind of help they’ll need is.

agree with you, it has to be rephrased.
The background is that there is a lot of activity in GSoC. If all of them ask question what can be solved by google it up within a minute, it is a real pain explain it to all.
At certain point we have to protect ourselves, avoiding that we are overrun by question and missing the one who really need support.
It is thin line between blockage and asking for independent troubleshooting.

How shall we solve this dilemma?

bedwardly-down · 2020-02-25T14:23:35.238Z

PackElend:

The background is that there is a lot of activity in GSoC. If all of them ask question what can be solved by google it up within a minute, it is a real pain explain it to all.
At certain point we have to protect ourselves, avoiding that we are overrun by question and missing the one who really need support.
It is thin line between blockage and asking for independent troubleshooting.

I see your point there. I'm not completely sure what the best option would be here. The core problem with them Googling answers to their questions is that the solutions they come up with may not be remotely what you are looking for, leading to a nightmare on your end too.

Is there any way to increase the amount of help you have so that you can focus on what really needs it? Maybe have a system of checks where lower level users review the students' proposals before they get to you?

PackElend · 2020-02-25T16:12:24.156Z

bedwardly-down:

Maybe have a system of checks where lower level users review the students’ proposals before they get to you?

that would help fore sure, we could says

google 5 min
ask the community
mention specific user

Moreover, we could agree on loose multi-level support

community
very active user
GSoC programm mentors etc.

that could mitigate the message

bedwardly-down · 2020-02-25T18:39:56.169Z

PackElend:

Moreover, we could agree on loose multi-level support

community

very active user

GSoC programm mentors etc.

that could mitigate the message

Anyway to enact concrete roles outside of mods and users? I like this and it's already sort of in place.

PackElend · 2020-02-25T21:27:50.091Z

bedwardly-down:

mods

mods are

not that much

grafik352×515 17.8 KB

grafik302×582 20.4 KB

bedwardly-down:

users

that is anyone but not all of them are as deeply involved as you

sunnyrahul25 · 2020-03-01T18:14:00.658Z

I think , it would be highly helpful if there is documentation on the codebase and its organization.
I admit I am new to react, There are a lot modules used in Joplin which makes reading through the source code difficult and hard to navigate.
An example about project layout would be neovim-project-layout
Some files are too long (1000 lines) they have multiple classes, may be this something that could be improved through refactoring the code.

rishabh.malhotra · 2020-03-01T19:46:00.823Z

I disagree, since it’s opensource the codebase it constantly evolving and it would be really really hard to maintain a documentation for the codebase, secondly, I’m with you, it might seem a bit daunting at first but you just need to get your hand dirty and dwell in the code base, piece by piece it will start making sense, one recommendation I can give you for easy navigation is use the search file feature in VSCODE, by typing few keyword you can easily find out which file is affecting the part of the codebase you want to edit.

Annotation 2020-03-02 0117361956×786 116 KB

sunnyrahul25 · 2020-03-01T20:11:12.968Z

Thank you, your recommendation is really helpful. I do use search feature (grep) to locate relevant part of source code and code folding to understand the large files but this is not good for understanding the overall structure of the project.
Consider this example from neovim.
If I want to make a certain change,I know where I should look into the source code.

sc980×432 41.7 KB

If the code has been documented about high level components this would be more helpful for new contributors.

laurent · 2020-03-01T23:22:18.646Z

Perhaps some high level doc about the app architecture would help? Do you have any example of an open source project that provide a good arch doc that we could take inspiration from?

There are always things to improve but overall I think the code is relatively well organised, with models, services, views, etc to split functionality.

bedwardly-down · 2020-03-01T23:54:22.337Z

Despite my belly-achings about there not being enough documentation for code and whatnot, I’ll agree with this. @rishabh.malhotra I think a good compromise would be to go the route that Facebook, the creators of Reactjs, have gone and make the documentation primarily about what’s a fixture in the app and then what breaking changes are being planned that contributors need to know about ahead of time. They’re not fully open about every single thing to the “T”, but offer enough that guys like me are happy.

It is impossible to fully keep up with what’s what with the limited resources this project has in its current state but I have more of a gripe with transparency than anything else. When I say transparency, I strongly believe in open discussion about the little things that could always make this project better, even if they never go anywhere. And this project is a lot more transparent than my initial thoughts, so not as huge of a problem for me.

rabeehrz · 2020-03-02T07:33:18.665Z

Writing code documentation is very important. What I do now is what @rishabh.malhotra is doing. But it is hectic and takes some time. Writing code with documentation helps a lot. Especially when it is an open-source project, a lot of collaborators with different levels of experience will be working together and good documentation makes everyone’s life a lot easier. I believe that when a project is said to be open source, Documentation for the project is assumed. I’m 100% for adding docs to Joplin.

As discussed above, the best option would be readthedocs. It is very easy to use and documentation becomes very easy. Initially implementing would be a bit difficult because there are a lot of functions that already exists in the code, but it should be alright.

Similiar to Google Summer of Code, there is Google Season of Docs. I think Joplin should participate in the next one.

If we do plan to implement documentation right now, I’m would love to work on it as well.