Contributors mailing list archives

Browse archives


Re: A meeting with the functionals that feel excluded by the OCA

Open for Small Business, Graeme Gellatly
- 28/09/2017 10:32:30
Doc Standards: A good place to start is here -

Was recommended to me by the docs team for a very large open source contributor a few years ago.  Well worth it.  I have a copy somewhere, just the kind of book that moves about a lot.  It's cheap anyway.

On Thu, Sep 28, 2017 at 9:17 PM, Jairo Llopis <> wrote:
I agree that we need to be technical to get the work done, but I also agree that newcoming is not easy unless you go to a code sprint.

I myself were newbie some time ago, and I never used a runbot until somebody told me it was that little blue button under that little colored badge in a PR that leads me to a instance with your code running. And you know what? I read a lot! But that's not written anywhere!

Also, for instance, here you can find a link to git docs under "Get familiar with git". Personally I think any link under is a much better place to "Get familiar with git".

I also have friends that have been programmers for a long time, and need to recycle themselves, and ask me about my work in OCA... And I don't really know where to lead them to! We use a lot of tools that are unknown to the average human, and functionals are those kind of humans.

Another good point: did you realize all docs are in English, but not all repos are in English? Many people in my country don't speak fluent English. Maybe not guidelines, but, which claims to be international, could care a bit more about translations and teaching newbies how to use online translators to communicate in OCA channels.

Here and there you can easily understand why OCA is a hard place (also starting from the point that Odoo is a hard place by itself too).

So I think the real newcoming problem for OCA is that docs were written by techies, that tend to assume reader's previous knowledge. But the same way we have coding standards, we also need doc standards. Docs need usability too (i.e., as soon as I open this page I know I'm not gonna read it 😂).

My proposal is that functional OCA experts (we have a few) meet with functional OCA newbies in the code sprint, and they sit together around a table to improve OCA docs, and maybe even define documenting standards.

You just have to make a simple heat map UX experiment:
  1. Define a set of tasks that a newcomer might want to achieve, depending on their profile.
  2. Sit behind them and ask them to do those tasks, receiving no input from you.
  3. Put a color in their cell that indicates you and his experience
  4. Add some improvement notes from him and from you.
  5. Go to the next newbie.

Then you can use your today's newbies to instruct your tomorrow's newbies by contributing to newcomer docs. That can be a good introduction to recursion for a functional person!😁

    Post to: