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 > >
