You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@fineract.apache.org by Aleksandar Vidakovic <ch...@monkeysintown.com> on 2026/09/01 00:19:24 UTC
Re: docs growth over time, new generated content
How about transforming into multiple pages instead one huge document?
There's an asciidoc extension for that and I think Aurora can do that too.
On Mon, 31 Aug 2026, 19:53 Adam Monsen, <me...@apache.org> wrote:
> We generate https://fineract.apache.org/docs/develop/ with Asciidoctor
> from asciidoc sources in
> https://github.com/apache/fineract/tree/develop/fineract-doc .
>
> The HTML version of the docs has grown over time, increasing significantly
> in size with v1.15.0 and recent builds off develop (1.16.0-SNAPSHOT).
>
> From the sources for our project website
> <https://github.com/apache/fineract-site/>, we find:
> *Date* *Path* *Size*
> Oct 11, 2025 docs/1.12.1/index.html 1.6M
> Oct 13, 2025 docs/1.13.0/index.html 1.9M
> Dec 22, 2025 docs/1.14.0/index.html 1.9M
> Jul 10, 2026 docs/1.15.0/index.html 2.8M
> Aug 31, 2026 docs/1.16.0-SNAPSHOT/index.html 5.6M
>
> https://fineract.apache.org/docs/develop/ still loads OK for me on
> desktop and mobile, but I think we should keep an eye on this size trend.
>
> Besides the size, I think it's worth asking if the [new] content is useful.
>
> https://fineract.apache.org/docs/develop/#_per_package_reference stands
> out to me... that section alone adds 286 pages to the PDF output (550 pages
> without, 836 pages with). The section is generated from ./gradlew
> architectureMetricsReport, saved in generated-package-overview.adoc, and
> included by cross-feature-boundary-violations.adoc. It could instead be
> generated on-demand / as-needed.
>
> Thoughts?
>
> And re: generated-package-overview.adoc / "Cross-Feature Boundary
> Violations" overall... it looks interesting, but is it something we want to
> keep in our docs, read often, refer back to ...? It seems more appropriate
> for a blog post, case study, FSIP, or project page specifically about
> modularizing Fineract. Side question: Was it AI-generated? I'm noticing
> many em-dashes, ~85 character line wrapping
> <https://issues.apache.org/jira/browse/FINERACT-2795>, and just the
> length of the file itself (1,500 lines).
>
> --
> Adam Monsen
> Software Engineer » Mifos Initiative
> Release Manager » Apache Fineract
> Author » Steadfast Self-Hosting
> PGP key » 0xA9A14F22F57DA182
>
>
Re: docs growth over time, new generated content
Posted by Adam Monsen <am...@mifos.org>.
Sounds good, thank you James and Aleks! I'm fine with whatever
splitting/refactoring makes sense to y'all.
Anyone else have feedback re: generated-package-overview.adoc and
cross-feature-boundary-violations.adoc?
Re: docs growth over time, new generated content
Posted by James Dailey <ja...@gmail.com>.
+1
I think those different orientations make sense
Onboarding new dev - how to get started ?
Technical Reference for all dev - how does it work?
Functional documentation - what’s does it do?
Release maintenance - how do we release
Sent from Gmail Mobile
On Tue, Sep 1, 2026 at 1:22 PM Aleksandar Vidakovic <
cheetah@monkeysintown.com> wrote:
> ... in the end: probably the content is not only one book/documentation...
> at the moment this is more like a kitchen sink... remember that we started
> out with 3 pages taken from the old handwritten HTML documentation...
>
> I can easily see to split up the content e.g. in separate "books":
>
> - developer onboarding
> - detailed technical documentation with architecture diagrams etc.
> - business/functional documentation
> - maintainer documentation (including release process)
>
> ... no claim that this is how it should be split up, but one way or
> another we can split things up.
>
> On Tue, Sep 1, 2026 at 9:46 PM Adam Monsen <am...@mifos.org> wrote:
>
>> Got any other feedback re: generated-package-overview.adoc and
>> cross-feature-boundary-violations.adoc? I have strong opinions about
>> those.
>>
>>
>> Aleks wrote:
>>
>>> How about transforming into multiple pages instead one huge document?
>>
>> Not an option for PDF (or is it?).
>>
>> For HTML I like the simplicity of a single large manual/document, but I
>> guess if we worked out an easy/fast way to search a split-up manual, sure,
>> that could work. There are of course many ways to accomplish splitting and
>> searching, but so far it hasn't been necessary and I'd prefer to avoid it.
>>
>
Re: docs growth over time, new generated content
Posted by Aleksandar Vidakovic <ch...@monkeysintown.com>.
... in the end: probably the content is not only one book/documentation...
at the moment this is more like a kitchen sink... remember that we started
out with 3 pages taken from the old handwritten HTML documentation...
I can easily see to split up the content e.g. in separate "books":
- developer onboarding
- detailed technical documentation with architecture diagrams etc.
- business/functional documentation
- maintainer documentation (including release process)
... no claim that this is how it should be split up, but one way or another
we can split things up.
On Tue, Sep 1, 2026 at 9:46 PM Adam Monsen <am...@mifos.org> wrote:
> Got any other feedback re: generated-package-overview.adoc and
> cross-feature-boundary-violations.adoc? I have strong opinions about
> those.
>
>
> Aleks wrote:
>
>> How about transforming into multiple pages instead one huge document?
>
> Not an option for PDF (or is it?).
>
> For HTML I like the simplicity of a single large manual/document, but I
> guess if we worked out an easy/fast way to search a split-up manual, sure,
> that could work. There are of course many ways to accomplish splitting and
> searching, but so far it hasn't been necessary and I'd prefer to avoid it.
>
Re: docs growth over time, new generated content
Posted by Adam Monsen <am...@mifos.org>.
Got any other feedback re: generated-package-overview.adoc and
cross-feature-boundary-violations.adoc? I have strong opinions about those.
Aleks wrote:
> How about transforming into multiple pages instead one huge document?
Not an option for PDF (or is it?).
For HTML I like the simplicity of a single large manual/document, but I
guess if we worked out an easy/fast way to search a split-up manual, sure,
that could work. There are of course many ways to accomplish splitting and
searching, but so far it hasn't been necessary and I'd prefer to avoid it.