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. 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>. > > 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. > > 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? >> >> 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. >> >> I will update the current documentation in the site repo when we build >> the next release. 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 >> >>
