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