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