Hello everyone,I've updated the README PR draft and changed the following points of the initial version:
1. I've replaced the mission statement, i.e. the very first part of the README. I took the text from Javier Borkenztain's email, because it seemed to have most votes in favor of it. Note that the title on top of everything is still the same ("Apache Fineract: A Platform for Microfinance"). I made a suggestion for its replacement, but there was no discussion, as far as I can see.
2. James Dailey, you asked for "not referencing Mifos in the Readme", and Paul agreed. I have therefore removed all references to Mifos. I don't think that makes sense and firmly believe it is unhelpful to visitors (and Fineract shoots itself in the foot). I dropped the section on API clients and demos, because I didn't see how this could possibly be rephrased without mentioning the "Mifos" word. (Why, James, are top representatives of vendors in the PMC okay, a roadmap (to a considerable extent) shaped by vendor requirements is okay - but saying Mifos in the README is not? We all have to recognize technical dependencies in software. We should recognize all of afore as non-technical, practical dependencies - we might like it or not.) If anyone disagrees with the removal of the section, please make a concrete proposal - I'm more than happy to bring it back.
3. I've removed the TOC, because Adam Monsen suggested so, although I disagree again. More than anything else, a TOC gave future editors an idea of where content is to be inserted (and some prior editors clearly had not paid much attention); it gave the reader an idea of where to look and what to expect; the times when a TOC required maintenance are over: any change of the README is hopefully proofread by AI - in the wake of which the TOC is updated automatically.
4. In the first version, I had assembled a chapter on "GUIDELINES FOR CONTRIBUTING CODE", based on existing sections. I have moved all of this and much, much more to CONTRIBUTING, because Adam Monsen and I are in favour of it, and no one seemed against it. Please read the text of CONTRIBUTING, because I added, rephrased and restructured content.
Initially I thought of moving significant parts of the "Instructions" to the one-page platform documentation. (In this context, Adam Saghy and I considered removing the section on Minikube altogether.) But I now think we should get a first README version merged. So many changes already! The platform documentation would profit from its own overhaul. We can still hone small aspects of the README later. Let's get a new baseline for the README! I have retracted the draft status.
Felix On 10/10/2025 03:15, Paul wrote:
👍 On Thu, Oct 9, 2025 at 6:39 PM James Dailey <[email protected]> wrote:To repeat what I wrote in the github comments... +1 This is great progress. I would however like to be even more explicit about not referencing Mifos in the Readme. To reference a Vendor in the README is highly irregular in any other apache project. I think it might be appropriate to have other open source projects listed somewhere... i.e. "the following projects have committed to work on or with Fineract - external site referenced here warning links take you away from Apache.org... ... then with some links to those GitHub repos. But describing a packaging approach with Mifos (as a vendor) is not appropriate. It would be more appropriate to have a listing of all known vendors of Fineract on the website, not the README. It fundamentally is against the Vendor neutrality obligation of the project. On Thu, Oct 9, 2025 at 2:25 PM Adam Monsen <[email protected]> wrote:On Fri, Oct 3, 2025 at 6:39 AM Felix van Hove <[email protected]> wrote:https://github.com/apache/fineract/pull/5076TL;DR - Great work so far! 2. I suggest to move some parts of the current README somewhere else.Yes! 100% agree. I'd love to get the readme down to "one page" (whatever that means--let's just say *very* succinct). The rest can live in official docs or wiki. ~50% of the existing readme content should be moved to the official docs and ~50% to the wiki. ( By "official docs" I mean the asciidoc sources in fineract-doc <https://github.com/apache/fineract/tree/develop/fineract-doc/src/docs/en>. ) I attached my suggestion. You can view it rendered here <https://codeberg.org/meonkeys/fineract-brief-readme> or here <https://git.disroot.org/meonkeys/fineract-brief-readme> (wait for it -- sometimes it takes a few seconds for the charts to render). Of course if you accept this it's still only a third of the work, the rest of the work is updating official docs, wiki, and a couple other markdown files (see below).- First of all, have you had a look at the CONTRIBUTING document? Contrary to the README, it's too short. Is it okay, if I move what is now "Guidelines for Contributing Code" over?Sure, or to the official docs. And CONTRIBUTING.md should be updated and kept short.- Secondly, could we not move half of what is under "Instructions" now to the documentation page (https://fineract.apache.org/docs/current/)Yes, please do.3. I would like to add a section "Troubleshooting", but need your input for it.This can go in the official docs too, once we have content for it.4. The current text remains extraordinarily long for a README, even if we move some sections somewhere else. To mitigate its complexity I have added a hopefully better structure to it (moved sections etc.) and a Table of contents. Okay?I don't want to add nor maintain a TOC. Let's just make the readme so short we don't need one. (side note: many tools generate a TOC for you by scanning Markdown headings, e.g. Vim Markdown <https://github.com/preservim/vim-markdown> and Markdown Viewer <https://addons.mozilla.org/en-US/firefox/addon/markdown-viewer-webext/> ). 5. I've removed and/or merged a few sections.👍 6. I'm not happy with the current DATABASE section and its position,suggestions welcome.Move to wiki or official docs or axe it. Final thought: content in STATIC_WEAVING.md should be moved to official docs or wiki.
