Archives
Contributors
The OCA Functional Working Group asks for your help!
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.
You need to have a Github account and sign the OCA CLA
You would have to fork the repository (well, here we already have lost most of the non-technical people).
Then edit the files of the Read Me using the Web Editor (so you can add images).
Download your images in the right folder than insert them into the file by Drag & Drop
Create a commit and a PR.
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
by Julie LeBrun - 07:31 - 23 Apr 2024
Follow-Ups
-
Re: The OCA Functional Working Group asks for your help!
Hello everyone,
Given that documentation is the first interaction many have with our modules, it's crucial that the READMEs for each module and repository are clear, informative, and standardized. Currently, each README serves as an essential introduction to its respective module or repository, but many could benefit from further review and content enrichment.
With the advancement of AI technologies, we have a great opportunity to use these tools to efficiently review and generate content. This will not only improve the quality of our documentation but also make the modules more accessible and easier to use for new users and contributors.
I suggest we start a project to review the existing READMEs. This project could include the following steps:
1. **Initial assessment of all existing READMEs** to identify those that need urgent improvements.
2. **Development of a style guide or template** to ensure all READMEs follow a consistent format and contain all necessary information.
3. **Use of AI tools** to assist in content review and generation where applicable, ensuring accuracy and quality.
4. **Peer review**, where community members can contribute feedback before finalizing the documents.
After completing this initial phase of reviewing and standardizing our READMEs, it would then be worthwhile to pursue a platform or a new process for building out the documentation further. This would ensure that our foundational documents are strong before we expand our documentation infrastructure.
Best regards,
Marcel Savegnago (https://escodoo.com.br)Em qui., 2 de mai. de 2024 às 10:02, Julie LeBrun <notifications@odoo-community.org> escreveu:Thank you everybody for taking the time to answer and help.We will be analyzing those options and communicating with some of you to have more information.
Julie LeBrunFormatrice & Analyste en applications de gestion intégrée+1 514-317-7944
Nouveau
Choisir un nom de projet comme un proDécouvrir Le jeu. 25 avr. 2024 à 11:17, Raphaël Valyi <notifications@odoo-community.org> a écrit :Hello,just a word to also encourage mkdocs if we aim at something additional to the current README markdown system. As Graeme said mkdocs is popular, capable and simple to manage (we really need to avoid big new tools that would be an infrastructure burden to manage). I think the README are slowly being improved, even if it's still by the module tech authors. In OCA/l10n-brazil we try to slowly improve these README for instance. At some point improving these README is lowering the entry barrier to the OCA and it somewhat makes sense that this entry barrier is lowered at the same time than the code is cleaned up and migrated so that non alien people will eventually succeed in their project with the OCA instead of just accumulating frustration by trying to attract at all cost people which will not make it with the current ecosystem (something that Odoo SA does quite a lot themselves in fact). So I mean it is not that bad if that documentation pace isn't as fast as some people who don't use to deliver real projects may dream...On Wed, Apr 24, 2024 at 11:27 AM Graeme Gellatly <notifications@odoo-community.org> wrote: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).
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.
You need to have a Github account and sign the OCA CLA
You would have to fork the repository (well, here we already have lost most of the non-technical people).
Then edit the files of the Read Me using the Web Editor (so you can add images).
Download your images in the right folder than insert them into the file by Drag & Drop
Create a commit and a PR.
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
_______________________________________________
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
_______________________________________________
Mailing-List: https://odoo-community.org/groups/contributors-15
Post to: mailto:contributors@odoo-community.org
Unsubscribe: https://odoo-community.org/groups?unsubscribe
--Raphaël ValyiFounder and consultant_______________________________________________
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
--Marcel Savegnago marcel.savegnago@escodoo.com.br +55 16 99122-7649 A informação transmitida destina-se apenas a pessoa ou entidade a quem foi endereçada e pode conter informação confidencial, legalmente protegida e para conhecimento exclusivo do destinatário. Se o leitor desta advertência não for o seu destinatário, fica ciente de que sua leitura, divulgação, distribuição ou copia é estritamente proibida. Caso a mensagem tenha sido recebida por engano, favor comunicar ao remetente e apagar o texto do computador.
The information transmitted is intended only for the person or entity to which it is addressed and may contain confidential and/or privileged material. Any review, retransmission, dissemination or other use of, or taking of any action in reliance upon, this information by persons or entities other than the intended recipient is prohibited. If you received this in error, please contact the sender and delete the material from any computer.
by Marcel Savegnago - 02:36 - 3 May 2024 -
Re: The OCA Functional Working Group asks for your help!
Thank you everybody for taking the time to answer and help.We will be analyzing those options and communicating with some of you to have more information.
Julie LeBrunFormatrice & Analyste en applications de gestion intégrée+1 514-317-7944
Nouveau
Choisir un nom de projet comme un proDécouvrir Le jeu. 25 avr. 2024 à 11:17, Raphaël Valyi <notifications@odoo-community.org> a écrit :Hello,just a word to also encourage mkdocs if we aim at something additional to the current README markdown system. As Graeme said mkdocs is popular, capable and simple to manage (we really need to avoid big new tools that would be an infrastructure burden to manage). I think the README are slowly being improved, even if it's still by the module tech authors. In OCA/l10n-brazil we try to slowly improve these README for instance. At some point improving these README is lowering the entry barrier to the OCA and it somewhat makes sense that this entry barrier is lowered at the same time than the code is cleaned up and migrated so that non alien people will eventually succeed in their project with the OCA instead of just accumulating frustration by trying to attract at all cost people which will not make it with the current ecosystem (something that Odoo SA does quite a lot themselves in fact). So I mean it is not that bad if that documentation pace isn't as fast as some people who don't use to deliver real projects may dream...On Wed, Apr 24, 2024 at 11:27 AM Graeme Gellatly <notifications@odoo-community.org> wrote: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).
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.
You need to have a Github account and sign the OCA CLA
You would have to fork the repository (well, here we already have lost most of the non-technical people).
Then edit the files of the Read Me using the Web Editor (so you can add images).
Download your images in the right folder than insert them into the file by Drag & Drop
Create a commit and a PR.
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
_______________________________________________
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
_______________________________________________
Mailing-List: https://odoo-community.org/groups/contributors-15
Post to: mailto:contributors@odoo-community.org
Unsubscribe: https://odoo-community.org/groups?unsubscribe
--Raphaël ValyiFounder and consultant_______________________________________________
Mailing-List: https://odoo-community.org/groups/contributors-15
Post to: mailto:contributors@odoo-community.org
Unsubscribe: https://odoo-community.org/groups?unsubscribe
by Julie LeBrun - 03:01 - 2 May 2024 -
Re: The OCA Functional Working Group asks for your help!
Hello,just a word to also encourage mkdocs if we aim at something additional to the current README markdown system. As Graeme said mkdocs is popular, capable and simple to manage (we really need to avoid big new tools that would be an infrastructure burden to manage). I think the README are slowly being improved, even if it's still by the module tech authors. In OCA/l10n-brazil we try to slowly improve these README for instance. At some point improving these README is lowering the entry barrier to the OCA and it somewhat makes sense that this entry barrier is lowered at the same time than the code is cleaned up and migrated so that non alien people will eventually succeed in their project with the OCA instead of just accumulating frustration by trying to attract at all cost people which will not make it with the current ecosystem (something that Odoo SA does quite a lot themselves in fact). So I mean it is not that bad if that documentation pace isn't as fast as some people who don't use to deliver real projects may dream...On Wed, Apr 24, 2024 at 11:27 AM Graeme Gellatly <notifications@odoo-community.org> wrote: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).
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.
You need to have a Github account and sign the OCA CLA
You would have to fork the repository (well, here we already have lost most of the non-technical people).
Then edit the files of the Read Me using the Web Editor (so you can add images).
Download your images in the right folder than insert them into the file by Drag & Drop
Create a commit and a PR.
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
_______________________________________________
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
_______________________________________________
Mailing-List: https://odoo-community.org/groups/contributors-15
Post to: mailto:contributors@odoo-community.org
Unsubscribe: https://odoo-community.org/groups?unsubscribe
--Raphaël ValyiFounder and consultant
by "Raphaël Valyi" <rvalyi@akretion.com> - 05:16 - 25 Apr 2024 -
Re: The OCA Functional Working Group asks for your help!
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).
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.
You need to have a Github account and sign the OCA CLA
You would have to fork the repository (well, here we already have lost most of the non-technical people).
Then edit the files of the Read Me using the Web Editor (so you can add images).
Download your images in the right folder than insert them into the file by Drag & Drop
Create a commit and a PR.
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
_______________________________________________
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
by "Graeme Gellatly" <graeme@moahub.nz> - 04:26 - 24 Apr 2024 -
Re: The OCA Functional Working Group asks for your help!
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).
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.
You need to have a Github account and sign the OCA CLA
You would have to fork the repository (well, here we already have lost most of the non-technical people).
Then edit the files of the Read Me using the Web Editor (so you can add images).
Download your images in the right folder than insert them into the file by Drag & Drop
Create a commit and a PR.
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
_______________________________________________
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
by Victor - 03:51 - 24 Apr 2024
