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