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

danielleschultz · 2020-02-19T20:40:17.730Z

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

Thanks.

laurent · 2020-02-20T12:47:06.600Z

@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.

bedwardly-down · 2020-02-20T17:13:25.420Z

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?

bedwardly-down · 2020-02-20T19:52:32.635Z

@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.

Runo-saduwa · 2020-02-20T20:02:49.415Z

@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

Runo-saduwa · 2020-02-20T20:06:30.545Z

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

bedwardly-down · 2020-02-20T20:13:39.760Z

I’m off work today and am briefly looking into it myself. I don’t have much of a clue about how to use it but am willing to learn. I also think that having a #GSoC-Doc Discord channel for everyone that is contributing directly to this project would help everyone stay up to date better. What do you guys think?

I really think this would be an excellent project to get going and submitted for GSoC

PackElend · 2020-02-21T21:49:49.940Z

bedwardly-down:

I also think that having a #GSoC-Doc Discord channel for everyone that is contributing directly to this project would help everyone stay up to date better. What do you guys think?

it is good for quick talks, but information there are lost, so anything what shall be available in the community has to be in the forum.
We are working on it to improve the flow of information.

Runo-saduwa:

I’ll also need to readthedocs.io to understand how it’s used, i

bedwardly-down:

I’m off work today and am briefly looking into it myself.

I'm not that much further, I only noticed that it is used very often and you can quickly create structures docs.
Give me some idea of the first structure and we will continue from there.
Idea:

Architecture
Style
Def tools
Build
- checks
Contribution
- style
- show proof of fix

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