Reg: Documentation for contributors

[kusht...@gmail.com]

Hi Team,

As the call for proposals is open, I would like to present my propose few idea and interest in handling a few of the topics mentioned in the notice.

Regarding documentation for contributors

For the following, I propose that we should add a header navigation item in our ongoing developing documentation site which may rather redirect to another page or a new website depending on what community feels appropriate. As a contributor when I first started contributing to OpenRefine, I felt there are various things which we can document more appropriately to have smoother contributor on-boarding.

• A welcome bot in our Gitter channel which will give out an automated response whenever a new contributor jumps in & say `Hello World`, we can change the world according to our need. In the automated response, we can redirect to the documentation site where all the required info will be populated.
• We need to document the architecture of OpenRefine & give a repository overview simplifying how our frontend code is organised and how our backend service works. OpenRefine's UI directory and structure need to be presented in a simpler manner by which the contributor can understand which piece of code is responsible for what, and which file should I change to see changes on the following page. Adding more to this, a video tutorial/walkthrough of OpenRefine's codebase will be cream to the top.
• Pull request process needs to be jotted down & the contribution workflow starting from how to get yourself an issue to how to get your PR successfully merged need s to be exposed.
• Other areas which can be separated from the basic contributing documentation can include documenting the release process, setting up IDE, and testing guidelines.
• One thing which I would like to propose from my side to establish governance in OpenRefine Organisation which would clearly highlight what roles we have like Org Member, Contributor, Maintainer and Admin.

Thanks & Regards 

Kush Trivedi

[Antonin Delpeuch (lists)]

Hi Kush,

Again I would say that this is too coarse-grained - you are proposing
many different things!

For instance the single topic of IDE setup would deserve to have its own
thread. What are the current problems people encounter when setting up
their IDEs? Which ones work well at the moment, which ones don't? What
would we need to change to the repository to improve that?

But for the sake of getting the discussion going, let me respond to your
first proposal, the welcome bot.

Do you have examples of FOSS projects where such bots are in place? Are
they helpful? My experience with chatbots is that they are often quite
frustrating, but perhaps you have had good experiences with them. As a
new contributor landing in the project, why would I want a "hello world"
from a bot? How much effort is it to set one up, and what sorts of
questions would they be capable of answering?

Best,
Antonin

On 02/09/2020 16:59, kusht...@gmail.com wrote:
> Hi Team,
>
> As the call for proposals is open, I would like to present my propose
> few idea and interest in handling a few of the topics mentioned in the
> notice.
>

> *Regarding documentation for contributors*
> *
> *

> For the following, I propose that we should add a header navigation item
> in our ongoing developing documentation site which may rather redirect
> to another page or a new website depending on what community feels
> appropriate. As a contributor when I first started contributing to
> OpenRefine, I felt there are various things which we can document more
> appropriately to have smoother contributor on-boarding.
>

> * A welcome bot in our Gitter channel which will give out an automated

> response whenever a new contributor jumps in & say `Hello World`, we
> can change the world according to our need. In the automated
> response, we can redirect to the documentation site where all the
> required info will be populated.

> * We need to document the architecture of OpenRefine & give a

> repository overview simplifying how our frontend code is organised
> and how our backend service works. OpenRefine's UI directory and
> structure need to be presented in a simpler manner by which the
> contributor can understand which piece of code is responsible for
> what, and which file should I change to see changes on the following
> page. Adding more to this, a video tutorial/walkthrough of
> OpenRefine's codebase will be cream to the top.

> * Pull request process needs to be jotted down & the contribution

> workflow starting from how to get yourself an issue to how to get
> your PR successfully merged need s to be exposed.

> * Other areas which can be separated from the basic contributing

> documentation can include documenting the release process, setting
> up IDE, and testing guidelines.

> * One thing which I would like to propose from my side to establish

> governance in OpenRefine Organisation which would clearly highlight
> what roles we have like Org Member, Contributor, Maintainer and Admin.
>
> Thanks & Regards 
> Kush Trivedi
>

> --
> You received this message because you are subscribed to the Google
> Groups "OpenRefine Development" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to openrefine-de...@googlegroups.com
> <mailto:openrefine-de...@googlegroups.com>.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/openrefine-dev/b8b82de6-4c6d-4d01-ad56-9c3548734e72n%40googlegroups.com
> <https://groups.google.com/d/msgid/openrefine-dev/b8b82de6-4c6d-4d01-ad56-9c3548734e72n%40googlegroups.com?utm_medium=email&utm_source=footer>.

[kusht...@gmail.com]

Hey Antonin,

About the chatbots, I have had the experience of bots in coala, fossasia, and few cncf sub-projects. What the bot does is, suppose if anyone new pops into OpenRefine Gitter channel, there first and the obvious question is to how to get started and how to contribute in community and our reply is to point the contributor to the wiki page and the contributing.MD file. This is where the bot will help us if the new contributor just pops in and types the trigger word, the bot can give the response which we used to give them.

Given above is the very basic use-case of the bot which is mostly useful in case when someone asks a similar question.

About the IDE, I experienced few errors with Sublime Editor when I set up OpenRefine like syntax detection and jquery intellisense, but recently I have switched to VS-Code and VS-Code gives you the extension recommendation as soon as you would open up a OpenRefine workspace. What we can do over here is give instructions on how to set-up VS-Code and recommended extension to have smooth development and contribution flow with OpenRefine upstream.

Thanks & Regards

Kush