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

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

same idea here, but GSoC is the most urgent currently

1 Like

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?

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

2 Likes

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

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

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

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?

2 Likes

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?

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

  1. community
  2. very active user
  3. GSoC programm mentors etc.

that could mitigate the message

2 Likes

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

mods are

not that much

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

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.

1 Like

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.

2 Likes

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.


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

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.

2 Likes

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.

2 Likes

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.

2 Likes

I swear Pack brought Season of Docs up somewhere here or elsewhere, but i Approve!!!

3 Likes

I try to collect all inputs here

and

1 Like