Abhinav - Can this be resolved please? We're getting other contributions now that may conflict with this, and this is apparently stalled out for many weeks.
So, please move it forward now or we will have to consider the effort abandoned. Send the link to the proposed PR and have it linked to the Jira ticket. ...it is better to be incrementally better and not let the perfect be the enemy of the merely good. Thanks, On Mon, Apr 22, 2024 at 4:56 AM Abhinav Sinha <abhinav7.si...@gmail.com> wrote: > I’ll provide an update by the end of the week. > > Thanks, > Abhinav > > From: James Dailey <jamespdai...@gmail.com> > Date: Sunday, April 21, 2024 at 7:32 PM > To: Abhinav Sinha <abhinav7.si...@gmail.com>, dev@fineract.apache.org < > dev@fineract.apache.org> > Subject: Re: New contributors guide (need your suggestions) > > This was an excellent start. What’s the status? > > We really need better onboarding materials - need your help. > > > On Mon, Mar 4, 2024 at 11:41 AM James Dailey <jamespdai...@gmail.com> > wrote: > >> If it’s better than what we have now, I am happy to commit it. >> >> Sent from Gmail Mobile >> >> >> On Mon, Mar 4, 2024 at 6:48 PM Abhinav Sinha <abhinav7.si...@gmail.com> >> wrote: >> >>> Sure, James, I will put the outstanding issues in a Jira ticket and >>> share it here. >>> Yes, I was thinking maybe we could do this PR, and then fix the >>> remaining issues incrementally. But, I would defer to you. >>> >>> Abhinav >>> >>> From: James Dailey <jamespdai...@gmail.com> >>> Date: Sunday, March 3, 2024 at 8:08 PM >>> To: dev@fineract.apache.org <dev@fineract.apache.org> >>> Subject: Re: New contributors guide (need your suggestions) >>> >>> Could you highlight the outdated information in some way in >>> the documentation? Or put in a jira ticket? >>> I think we want to move forward incrementally. >>> >>> Are you suggesting we do this PR first and then continue to work on it? >>> >>> >>> >>> >>> >>> On Sun, Mar 3, 2024 at 4:07 PM Abhinav Sinha <abhinav7.si...@gmail.com> >>> wrote: >>> >>>> Hello! >>>> >>>> I’ve truncated the README and extracted most of the information out to >>>> the asciidocs. Here’s the Pull Request with these changes - >>>> https://github.com/apache/fineract/pull/3765 >>>> >>>> This is still a Work In progress, though. Essentially, what I’ve done >>>> is just moved content from the readme to the asciidocs. There are a >>>> bunch of broken links in the current documentation, and some outdated >>>> information too. >>>> >>>> Please let me know if you have any suggestions on this. Appreciate it! >>>> >>>> Thanks, >>>> Abhinav >>>> >>>> From: Aleksandar Vidakovic <chee...@monkeysintown.com> >>>> Date: Tuesday, February 27, 2024 at 11:03 AM >>>> To: dev@fineract.apache.org <dev@fineract.apache.org> >>>> Subject: Re: New contributors guide (need your suggestions) >>>> >>>> Thanks Abhinav >>>> >>>> On Tue, Feb 27, 2024 at 9:38 AM Abhinav Sinha <abhinav7.si...@gmail.com> >>>> wrote: >>>> >>>>> I agree with your point- removing redundant documentation is going to >>>>> help a lot. So I’ll extract most of the information to the asciidocs and >>>>> keep the main README concise. >>>>> >>>>> >>>>> >>>>> I’ll update this thread with my changes over the weekend. Thanks for >>>>> the suggestions! >>>>> >>>>> >>>>> >>>>> Abhinav >>>>> >>>>> >>>>> >>>>> *From: *Aleksandar Vidakovic <chee...@monkeysintown.com> >>>>> *Date: *Monday, February 26, 2024 at 8:09 PM >>>>> *To: *dev@fineract.apache.org <dev@fineract.apache.org> >>>>> *Subject: *Re: New contributors guide (need your suggestions) >>>>> >>>>> ... I would keep the README as short and generic as possible and refer >>>>> to one source of truth to avoid frequent updates. The README contains in >>>>> its current form a lot of information, but is not really a great place to >>>>> keep things up to date; e. g. version numbers for certain components >>>>> (databases, libraries etc.) have to be maintained manually in the README >>>>> whereas in Asciidoc you can extract this information from the same Gradle >>>>> dependency management we use for the builds. Additionally we have at least >>>>> one Wiki and at least 2 Jira ticket instances (Apache Fineract, Mifos) >>>>> with >>>>> additional valuable information. >>>>> >>>>> >>>>> >>>>> That's a lot of places to search... but maintainability would be my >>>>> primary argument here. >>>>> >>>>> >>>>> >>>>> On Mon, Feb 26, 2024 at 9:09 PM Abhinav Sinha < >>>>> abhinav7.si...@gmail.com> wrote: >>>>> >>>>> I can update the current README to point to the asciidoc. Also, clean >>>>> it up a bit – so that it doesn’t have a lot of duplicate information. >>>>> >>>>> >>>>> >>>>> Abhinav >>>>> >>>>> >>>>> >>>>> *From: *James Dailey <jamespdai...@gmail.com> >>>>> *Date: *Monday, February 26, 2024 at 3:03 PM >>>>> *To: *dev@fineract.apache.org <dev@fineract.apache.org> >>>>> *Subject: *Re: New contributors guide (need your suggestions) >>>>> >>>>> A lot of people expect the readme. If we’re not maintaining it, then >>>>> let’s point from readme to ascii. >>>>> >>>>> >>>>> >>>>> Or, what’s the split? >>>>> >>>>> >>>>> Sent from Gmail Mobile >>>>> >>>>> >>>>> >>>>> >>>>> >>>>> On Mon, Feb 26, 2024 at 10:10 AM Abhinav Sinha < >>>>> abhinav7.si...@gmail.com> wrote: >>>>> >>>>> That makes sense Aleks! Thanks for pointing that out. Moving it to the >>>>> Asciidoc module now. >>>>> >>>>> >>>>> >>>>> Thanks, >>>>> Abhinav >>>>> >>>>> >>>>> >>>>> *From: *Aleksandar Vidakovic <chee...@monkeysintown.com> >>>>> *Date: *Monday, February 26, 2024 at 10:58 AM >>>>> *To: *dev@fineract.apache.org <dev@fineract.apache.org> >>>>> *Subject: *Re: New contributors guide (need your suggestions) >>>>> >>>>> ... @Abhinav why not add it to the Asciidoc module? Then we have it in >>>>> one place... this gets published also on fineract.apache.org (working >>>>> on regular updates)... >>>>> >>>>> >>>>> >>>>> On Sun, Feb 25, 2024 at 11:55 AM Abhinav Sinha < >>>>> abhinav7.si...@gmail.com> wrote: >>>>> >>>>> Thanks for the suggestions, James! I’ve added your comments regarding >>>>> communications to the guide (some of it verbatim). Here’s >>>>> <https://github.com/abhinav7sinha/fineract/blob/FINERACT-2023/first-time-contributors-guide/contributors/guide/contributing.md> >>>>> the current version. >>>>> >>>>> >>>>> >>>>> I agree with your assessment of the README file having a lot of >>>>> “getting started” info, and that we should move it to a separate place to >>>>> only keep “using it regularly” info in the main README. To this effect, >>>>> I’ve created a new file “dev-env-setup.md” in `/contributors/guide`. This >>>>> has instructions on how to set up a dev environment for Apache Fineract. >>>>> Have a look at the initial draft here >>>>> <https://github.com/abhinav7sinha/fineract/blob/FINERACT-2023/first-time-contributors-guide/contributors/guide/dev-env-setup.md>. >>>>> It’s just a copy of the original readme, but it is distilled to only >>>>> include the development environment setup instructions. >>>>> >>>>> >>>>> >>>>> Thanks, >>>>> >>>>> Abhinav >>>>> >>>>> >>>>> >>>>> *From: *James Dailey <jdai...@apache.org> >>>>> *Date: *Saturday, February 24, 2024 at 8:59 PM >>>>> *To: *dev@fineract.apache.org <dev@fineract.apache.org> >>>>> *Subject: *Re: New contributors guide (need your suggestions) >>>>> >>>>> Abhinav - Great initiative and much needed. >>>>> >>>>> >>>>> >>>>> The Apache Software Foundation (ASF) adage is: "If it didn't happen >>>>> on the list, then it didn't happen." >>>>> >>>>> >>>>> >>>>> if you're going to point to a slack channel, remember to point to the >>>>> Apache Fineract channel ==> >>>>> https://the-asf.slack.com/archives/C4QPZURQQ >>>>> >>>>> and, just as a reminder, all communications that happen off-list >>>>> should be brought back to the list, including ASF slack discussion. >>>>> >>>>> Normally, you should not discuss things off list, but if you do, then >>>>> you should summarize it on list. >>>>> >>>>> >>>>> >>>>> Example, if you discuss something "off list" on a slack channel, >>>>> especially one at Mifos slack, then you should summarize that >>>>> discussion here at Dev@fineract.a.o. >>>>> >>>>> By summarizing it, you are bringing into the official record of the >>>>> project. >>>>> >>>>> >>>>> >>>>> In terms of content: >>>>> >>>>> I think that the readme file has some useful "getting started" info >>>>> confused with "using it regularly" info. I think a clear separation of >>>>> those two scenarios is useful. >>>>> >>>>> >>>>> thanks >>>>> >>>>> >>>>> >>>>> >>>>> >>>>> >>>>> >>>>> On Sat, Feb 24, 2024 at 5:03 AM Abhinav Sinha < >>>>> abhinav7.si...@gmail.com> wrote: >>>>> >>>>> Hi, >>>>> >>>>> >>>>> >>>>> I am working on a new contributors guide for the Fineract project. >>>>> >>>>> >>>>> >>>>> The idea is pretty straightforward – it’s going to be the first link >>>>> any new contributor to Apache Fineract can visit, and it will have >>>>> everything they need to get started. >>>>> >>>>> >>>>> >>>>> We have a lot of good documentation scattered across READMEs, >>>>> docs.mifos.org, etc. I am trying to collate the ones needed for >>>>> first-time contributors in one place. Here >>>>> <https://github.com/abhinav7sinha/fineract/blob/FINERACT-2023/first-time-contributors-guide/contributors/guide/contributing.md> >>>>> is the initial draft currently on GitHub, we can move it to a different >>>>> place. >>>>> >>>>> >>>>> >>>>> Fineract’s README on GitHub is pretty good and has a lot of this >>>>> information. The new contributor’s guide will link to this README, but it >>>>> will have any additional info that a new contributor could be looking for >>>>> (a high-level overview of the contribution process, GSoC links, etc.) >>>>> >>>>> >>>>> >>>>> I am looking for any ideas that you may have on this guide, or any >>>>> documentation-related suggestions that you feel we can improve on. I also >>>>> want to take this opportunity to clean up the existing README, so anything >>>>> that you feel is missing, or needs change, pls let me know. >>>>> >>>>> >>>>> >>>>> Additionally, new contributors to Fineract - if you are facing any >>>>> difficulty with getting the right information, feel free to share, I would >>>>> love to hear your opinion/ideas. >>>>> >>>>> >>>>> >>>>> Thanks, >>>>> >>>>> Abhinav >>>>> >>>>>
