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<mailto: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<mailto:jamespdai...@gmail.com>> Date: Monday, February 26, 2024 at 3:03 PM To: dev@fineract.apache.org<mailto:dev@fineract.apache.org> <dev@fineract.apache.org<mailto: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<mailto: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<mailto:chee...@monkeysintown.com>> Date: Monday, February 26, 2024 at 10:58 AM To: dev@fineract.apache.org<mailto:dev@fineract.apache.org> <dev@fineract.apache.org<mailto: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<http://fineract.apache.org> (working on regular updates)... On Sun, Feb 25, 2024 at 11:55 AM Abhinav Sinha <abhinav7.si...@gmail.com<mailto: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<mailto:jdai...@apache.org>> Date: Saturday, February 24, 2024 at 8:59 PM To: dev@fineract.apache.org<mailto:dev@fineract.apache.org> <dev@fineract.apache.org<mailto: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<mailto: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<http://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