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 >>> >>>
