Thanks kindly! Here's my "yes, and"... James wrote:
> 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. Ok so our asciidoc documentation is dev-focused. That makes sense! I'm on board, and I'm glad we've got a solid foundation. Putting my dev hat on: I'd expect to find project info as follows... - how to build/test/install/deploy: quick reference in top-level readme, with gory details in asciidoc if/as necessary - APIs: in an API reference guide I know I'm preaching to the choir here, but *more/better documentation* won't solve problems like too many APIs and overcomplicated processes for building, deploying, securing, and releasing. The code itself must [also] be improved. Example: if the build is simplified, that top-level readme should almost write itself. Similarly for the other areas: a reasonable API is easier to document / tool-ify / necessitates less documentation. And I for sure also realize "clean up the API" and "simplify the deploy" may mean unendurable pain for a particular vendor or customer, and "the code must be improved" means the vision/focus/roadmap/community must be improved. 💞 Terence wrote: > 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'm hearing a strong reaction to the acronym "IDE". If so, I'm with you. I prefer a text editor. But I would hazard a guess that most Fineract code changes are done in an IDE lately, so as this thread revolves around making it easier for people to improve Fineract documentation, we should consider anyone who is [potentially] working on the docs. And, oh gosh, maybe it would be wise to s/people/people and AIs/ above, although I am having an emotional reaction as I write that. Asciidoc is simple markup language (IMHO) so I'm usually just editing the source in Vim. When I need a quick preview I use the Asciidoctor.js Live Preview browser extension <https://asciidoctor.org/news/2013/09/18/introducing-asciidoctor-js-live-preview/> and open index.adoc in my web browser. This nifty tool has been around a long time and works well. It renders Fineract's asciidoc into a coherent styled manual in less than one second on my computer. I usually use the extension in Firefox but includes don't work <https://github.com/asciidoctor/asciidoctor-firefox-addon/issues/21#issuecomment-73343904> (probably Firefox is more secure in this respect), so I use Chromium with Fineract's asciidoc. That shows an almost fully-rendered manual with proper styling from config.adoc, etc. Fineract has hundreds of includes so this is important. I said "almost fully-rendered" because there are some features that don't work (or I haven't got working) with Asciidoctor.js, like ftl template includes and diagrams. So when I need the "real thing", I run gradle asciidoctor. Takes 10-40sec to build an HTML manual (after the first run, which likely caches a bunch of the usual build products). I don't know why we have 136 asciidoc files. Seems a bit excessive. Maybe that's an optimization for editing asciidoc with an IDE? At least Vim is able to jump between them--somehow gf ("goto file") works even though I don't override includeexpr <https://github.com/habamax/vim-asciidoctor/blob/f553311b5db03440eb8d7035434d0405e4a2c559/ftplugin/asciidoctor.vim#L51> . One reason I dislike multiple asciidoc files is because that nifty browser extension only detects and instantly shows changes for the actual path you have open (not included files). Reloading is good, but instantaneous would be better. can "mostly structural" and "mostly content" be interpreted as DEV targeted > and User (API consumer) targeted respectively? No, I meant my changes to the asciidoc <https://github.com/apache/fineract/pull/4470> were more about improvements to the structure of the docs themselves: consistent language, bugs in asciidoc syntax, stuff like that. 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. Sounds like a fine addition to .github/workflows/build-documentation.yml . I support that.
