Felix Van Hove created FINERACT-2383:
----------------------------------------
Summary: Modernise README
Key: FINERACT-2383
URL: https://issues.apache.org/jira/browse/FINERACT-2383
Project: Apache Fineract
Issue Type: Improvement
Components: Docs
Affects Versions: 1.12.1
Reporter: Felix Van Hove
I suggest to improve the README shown on the start page of the Github project.
[https://github.com/apache/fineract/blob/develop/README.md]
1. Modernize "DEVELOPERS" section
Add a reference to the Fineract channel at Mifos. Don't link to
https://cwiki.apache.org/confluence/display/FINERACT/Fineract+101 , it's
obsolete.
2. Information regarding physical hardware requirements is missing
You need 16GB RAM and an 8 core processor to meaningfully install Fineract
3. Status of MariaDB vs. PostgreSQL is unclear
Under the section "REQUIREMENTS" the README states "MariaDB 11.5.2" as a
requirement. However it runs well with 12.0.2 too. It also runs with
PostgreSQL, anything beginning with version 17.0.
4. There is a section "IMPORTANT: If you use MySQL or MariaDB" which is not
important
The section commences "Recently (after release 1.7.0), we introduced improved
date time handling..." The whole section has become unimportant, because we
have Fineract 1.12.1 now. I suggest to create a new section "DATABASE" instead,
move some of the current content of "REQUIREMENTS" into it and put this
"IMPORTANT" section at its end.
5. Dead / useless links
"via environment variables (as with Docker container)", "build.gradle" (at the
end), "This is a demo video for Swagger-UI documentation, more information
here." (where "here" is a link), "Latest Release on Develop". "View change log"
should really point to
https://cwiki.apache.org/confluence/display/FINERACT/Fineract+Releases or to
https://github.com/apache/fineract/releases
6. Remove obsolete section "INSTRUCTIONS: How to build a WAR file"
Instead, rename "INSTRUCTIONS: How to build the JAR file" into "INSTRUCTIONS:
How to build for production" and add a sentence in the end: "We don't recommend
building Fineract as a WAR file, but it remains possible." A section titled
"INSTRUCTIONS: How to build for production" would better complement the
existing "INSTRUCTIONS: How to run for local development".
7. Section "TOMCAT CONFIGURATION"
Mentioning FINERACT_SERVER_TOMCAT_MAX_HTTP_FORM_POST_SIZE here, is a bit of a
surprise to me, because for development you don't need this configuration. For
production you shouldn't use Tomcat. Can anything similar be recommended for a
production context?
8. "GOVERNANCE AND POLICIES" is not a good title for the sections below it
E.g. "LOGGING GUIDELINES" is a subsection. I suggest to rename "GOVERNANCE AND
POLICIES" to "GENERAL GUIDELINES".
9. "VIDEO DEMONSTRATION" section is too old
This is just linking to a 9 years old video. I suggest to remove this section.
If you really want a demo of Fineract (which is very much based on Mifos web
app in the given example), create a new video before linking to it here.
10. Remove references to apiLive
apiLive is an obsolete way to document Fineract (and could be decommissioned
altogether). Also, don't say "The Swagger documentation (work in
progress...)...", but just refer to the Swagger documentation as the reference
now.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
