[
https://issues.apache.org/jira/browse/FINERACT-2383?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Felix Van Hove updated FINERACT-2383:
-------------------------------------
Description:
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.
This should be stated, as many newcomers stumble upon this (and invest a lot of
time in getting it running on too-small hardware and don't understand, why it
doesn't work).
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
Examples for dead and 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 section "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.
was:
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.
This should be stated, as many newcomers stumble upon this (and invest a lot of
time in getting it running on too-small hardware and don't understand, why it
doesn't work).
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.
> 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
> Priority: Minor
>
> 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.
> This should be stated, as many newcomers stumble upon this (and invest a lot
> of time in getting it running on too-small hardware and don't understand, why
> it doesn't work).
> 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
> Examples for dead and 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 section "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)
