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/5076 >> > > TL;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. >
