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