[
https://issues.apache.org/jira/browse/FINERACT-2383?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18024135#comment-18024135
]
Adam Monsen commented on FINERACT-2383:
---------------------------------------
Thank you Felix! Agreed our top-level README is an important resource.
h2. target audience
I agree with James the target audience of the README is and should be
developers.
h2. in general
To review, we have these doc resources:
# README
# wiki
# official docs
I think the top-level README should be pared down to a terse and useful "quick
start" guide for devs. That's it. Anything else should be moved to the wiki or
official docs. If you agree, let's add a disclaimer to the top.
The wiki (hosted by ASF, confluence, contains supplemental collaborative
documentation) is allowed to be a bit more messy and in flux, I think. I think
the wiki should have a wider target audience.
The official docs (asciidoc in source control under {{{}fineract-doc/{}}}),
built & published at [https://fineract.apache.org/docs/current/]) are where we
want to aim for high quality, illustrative, exhaustive content.
Ideally all these doc changes are coordinated with code changes to simplify
test/build/run/demo operations, as well as the product roadmap (wherever that
is).
h2. production
I think it's a good idea to say something about running in production, e.g.:
{quote}Fineract is powerful, flexible, and secure. Running Fineract just to try
it out is relatively easy. This might take a few minutes to complete for a
developer who has done it before. If you intend to use it for customers, be
aware that a proper Fineract production deployment can be very complex, costly,
and time-consuming. Considerations include: Security, privacy, compliance,
performance, service availability, backups, and more. The Fineract project does
not provide a comprehensive guide for deploying Fineract in production. You
will need dedicated IT resources skilled in enterprise Java applications. Or
you can pay a vendor for Fineract deployment and maintenance. Also, you will
find tips and tricks for deploying and securing Fineract in our [official
documentation|https://fineract.apache.org/docs/current/], and there are also
[community-maintained use cases on the
wiki|https://cwiki.apache.org/confluence/display/FINERACT/Hosting+Fineract].
{quote}
h2. specific feedback
# Sounds good, yep, please remove or update any outdated links/info.
# If you're sure about those hardware requirements, great -- I really have no
idea here. I think the word "meaningfully" is not helpful here. Just provide
minimum requirements for a dev to try it out (assuming we agree on audience and
purpose of the README).
# Maybe what's most useful here are the minimum db product versions required,
and which versions we test against.
# Ha! Nice. Yeah, how about we just axe it, or move it to the wiki if we think
someone still might get value out of it?
# Yep, again, please remove or update any outdated links/info.
# Sure, whatever you think is helpful here. I see elsewhere we say _We
recommend using the JAR instead of the WAR file deployment, because it's much
easier._
# No idea. Sure, axe it.
# Sounds fine.
# Agreed, axe it.
# Sounds good.
> 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
> Assignee: 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, but not pretending it is important, more
> rather an information for long-time users.
> 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? If not, I suggest to remove it without replacement.
> 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)
