1. Mailing Lists
  2. Contributors
  3. Re: The OCA Functional Working Group asks for your help!

Contributors mailing list archives

contributors@odoo-community.org

Browse archives

Re: The OCA Functional Working Group asks for your help!

Re: The OCA Functional Working Group asks for your help!

Avatar

Re: The OCA Functional Working Group asks for your help!

by "Graeme Gellatly" <graeme@moahub.nz> - 24/04/2024 16:25:49
I second mkdocs. All my non technical staff use it to build docs. Most.jist write markdown bit some use a specialised markdown editor although that seems to fail lintimg quite a bit.

It is trivial to automate linting and deploy on merge.

On Wed, 24 Apr 2024, 6:52 am Victor Champonnois, <notifications@odoo-community.org> wrote:

Hello Julie,

>Do you know of any tool that could easily allow to edit and create PRs of README files in GitHub without the need of having GitHub knowledge? Something similar to what Weblate does for .po files ?

I think Weblate directly commits on the main branch, it does not create a PR.

As Andreas says, the edit functionality in Github seems like the simplest approach. However, it requires to create a fork of the repo, and to make a PR, so it's still a big barrier. 

Victor Champonnois - Coop IT Easy
Tel : +32 475 81 01 12
On 24/04/24 07:44, Andreas Perhab wrote:
Hi Julie,

I think the edit button in github does most of the forking work for you and even helps with creating a PR when one is finished editing the readme (really any markdown file).
FireShot Capture 260 - OCA_maintainer-tools_ Odoo Maintainers Tools & conventions for OCA me_ - github.com.png

It puts images into /assets/{number}/{uuid} so that might need changing or we could just accept this additional directory.

regards Andreas



On Tue, 23 Apr 2024 at 19:32, Julie LeBrun <notifications@odoo-community.org> wrote:
Do you know of any tool that could easily allow to edit and create PRs of README files in GitHub without the need of having GitHub knowledge? Something similar to what Weblate does for .po files ?

Hello everybody!


During the last OCA Days, the OCA Functional Working Group (FWG) presented the work made on the Documentation Project.


This project was created by the FWG to help and attract functional people to contribute to modules documentation.


2 main options were analyzed


  • Using the existing Read Me file in the code so we have only one module documentation which regroups technical and functional information.

  • Using the GitHub Wiki on the repositories which could be really easy to put in place and use.


The decision was made to use the existing Read Me but to convert it into Markdown so it could be easier to use and to add images.


Following this decision, an issue was opened in GitHub about the use of the Wiki instead of Read Me : https://github.com/OCA/maintainer-tools/issues/606



BUT, we still have a big issue regarding this solution: the process to contribute to Read Me is really, really complicated for non-technicals.  


  1. You need to have a Github account and sign the OCA CLA

  2. You would have to fork the repository (well, here we already have lost most of the non-technical people).

  3. Then edit the files of the Read Me using the Web Editor (so you can add images).

  4. Download your images in the right folder than insert them into the file by Drag & Drop

  5. Create a commit and a PR.

  6. Finally, the changes would need to be approved by contributors who have those access rights.



So, we were thinking: if we add a Markdown tool that can be used to edit Read Me files and automatically push the changes into GitHub a little bit like the Weblate tool, we could combine the PROS of both options analyzed.



Does anyone have any idea of this kind of tool?


Thank you in advance for your help.



The OCA Functional Working Group

fwg@odoo-community.org



_______________________________________________
Mailing-List: https://odoo-community.org/groups/contributors-15
Post to: mailto:contributors@odoo-community.org
Unsubscribe: https://odoo-community.org/groups?unsubscribe

_______________________________________________
Mailing-List: https://odoo-community.org/groups/contributors-15
Post to: mailto:contributors@odoo-community.org
Unsubscribe: https://odoo-community.org/groups?unsubscribe

_______________________________________________
Mailing-List: https://odoo-community.org/groups/contributors-15
Post to: mailto:contributors@odoo-community.org
Unsubscribe: https://odoo-community.org/groups?unsubscribe

Reference