Hi Fineracters, Opinionated responses inline..
On Thu, Mar 20, 2025 at 9:13 PM James Dailey <jdai...@apache.org> wrote: > All - Bringing this back up. > > Thanks Adam. Documentation is definitely the last thing people seem to > want to work on. How should we change this? > > Asking devs to "do more" doesn't seem to be a successful strategy. > Agree We should have it as one of the checkmarks on the "things to verify before > you make your PR", however, that seems to be routinely ignored so not sure > it really helps. > > We could have a github action that checks to see if you included any > change to the asciidoc files - throws a non fatal error but at least > signals something. > > l think maybe we should organize a zoom call to discuss - get the most > prolific contributors together to see if there is some tooling approach or > way to use the jira tickets and the code changes themselves to create the > kind of documentation that would be useful. > > I think your question - who is this documentation for? is a > very important one. I don't believe it should be for the end users, but > rather it should be more focused on understanding the underlying > functionality behind the 900+ apis, as well as documentation on how to > build (with variations), how to deploy (variations), secure, how to do a > release, and similar topics. > > Thanks, > > > On Wed, Mar 5, 2025 at 9:30 AM Adam Monsen <amon...@mifos.org> wrote: > >> Great thoughts here James, thank you. I'll chime in because documentation >> is one of the main reasons I'm here again today, thanks to Ed & Mifos. >> >> James and I talked about this offline / off-list. I think the asciidoc in >> fineract-doc/ is great and we can continue to incrementally improve it. >> I've found asciidoctor to be reliable and consistent. Building the docs is >> a bit slow, but Victor showed us how IntelliJ provides a real-time >> preview of changes >> <https://lists.apache.org/thread/bf38vsnw1d49rx7ctzhvtrd9r9hrttwy>. >> > Sounds cool to IDE dependent devs, but pointless/repulsive to, e.g Emacs / Vim coders and people who seamlessly automate coding/deployment if that's your mojo. I have more documentation improvements coming, and we talked about how mine >> (mostly structural) probably won't conflict with those James will do >> (mostly content). And I don't mind rebasing my changes if/when they do >> conflict. >> > Adam: can "mostly structural" and "mostly content" be interpreted as DEV targeted and User (API consumer) targeted respectively? > As to automation: yep, we should do that. I'm not sure what the exact >> nature and priority of further docs automation should be, but I'm >> interested and I have ideas and opinions about it... I'll have more to >> share in the coming months as I continue to get up to speed. >> >> I'm going to submit a PR to https://github.com/apache/fineract-site/ >> soon to add the docs built from the v1.11 release maintenance branch to >> https://fineract.apache.org/docs/XYZ/ . >> >> So all that is fine and good, but looking at the commit history of >> fineract-doc/ (vs. the whole Fineract codebase), we are not consistently >> updating the asciidoc. I'd expect doc updates to be part of every PR! *This >> is the greatest area of opportunity for us to improve the docs*, in my >> humble opinion. And it is dang hard, I get that. The devs are already >> tasked to the hilt. But it's just gotta get done. >> >> There's a lot we could do to encourage and enforce doc updates along with >> code updates. For example, a checkbox in .github/PULL_REQUEST_TEMPLATE.MD >> might help (although I have strong feelings about how effective these >> checkboxes actually are in practice). Another idea: a Fineract >> documentation working group. David Higgins started one of these on the >> Mifos side, and over a dozen people are involved. >> >> Here's a naive question: who is the audience (of the HTML and PDF >> asciidoc build products)? Devs coding Fineract? Sysadmins installing >> Fineract? Users using Fineract? My guess is "all of the above" based on my >> reading of it (mostly skimming, if I'm being honest). >> >> On Tue, Feb 11, 2025 at 2:47 PM James Dailey <jdai...@apache.org> wrote: >> >>> Devs >>> >>> I believe that we need a better set of documentation at this project. >>> It would be helpful if it comes more automatically as part of development >>> processes. Any ideas? >>> >> How about CI/CD pipeline generatable docs auto-configured on the "develop" branch but through a Git hook approach unless it can be built within a minute. Output can be a git repo. > Currently the Fineract wiki pages are to manage the project and community >>> (with some legacy documentation) while the ascii doc files are versioned >>> for each release and contain more detailed information about the software. >>> The readme should point to both and describe for a dev setup. >>> >> asciidoc seems the best candidate to build on since it seems to already work, provided the build speed issue can be addressed by maybe throwing some Infra (CPU/GPU) at it? > I will update the current documentation in the site repo when we build the >>> next release. >>> >> Thanks, James, for taking this up If you have changes to ascii files - now’s a good time to offer them. >>> (Before Feb 21st). >>> >>> Also, the revamped landing page now more clearly points to these things >>> so now is a good moment to ask: >>> >>> What can we do to make documentation easier? Are there people interested >>> in this? >>> >>> Any questions? >>> >>> James >>> >> - Terence
