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

Reply via email to