Thank you, Oleg! I took that as lazy consensus and opened https://issues.apache.org/jira/browse/TIKA-4625 along with a PR.
The PR is largely just stubbed out. The PR is here: https://github.com/apache/tika/pull/2536 The best way to view the rendered content is to go to the branch: https://github.com/apache/tika/blob/TIKA-4625/docs/src/main/asciidoc/index.adoc I added some examples of living documentation for the configs. The .adoc's have links to unit tests that show the full configs for some of the parsers. We can expand this for server, grpc and the pipes components etc. Let me know what you think. Best, Tim On Thu, Jan 15, 2026 at 8:14 AM Oleg Tikhonov <[email protected]> wrote: > Hey Tim, > I love this idea. > It seems like asciidoc is a standard. > > +1 > > Thanks, > Oleg > > On Thu, Jan 15, 2026 at 3:10 PM Tim Allison <[email protected]> wrote: > > > For documentation, we have javadocs, confluence, and our website. > > > > Confluence is aging. The benefit of confluence is that non-committers can > > modify it directly. > > > > Some pros: > > a) keep documentation closer to the codebase. We'd just work in our > github > > repo > > b) this is easier for humans and claude/copilot/agents to maintain > > c) non-committers can still open prs against github. Slightly more > friction > > than confluence, but outside contributorship to confluence has been > minimal > > in recent years > > d) start fresh with all the 4.x modifications > > > > Some cons: > > a) yet another site for documentation > > b) another new tech involved > > > > I'm looking at what stormcrawler is doing with asciidoc, and it looks > > pretty good, e.g. > > > > > https://github.com/apache/stormcrawler/blob/main/docs/src/main/asciidoc/architecture.adoc > > > > The asciidoc plugin generates html that is shipped with the code, and the > > docs are rendered in github. > > > > Should we head in this direction? This would be additive for now. We > > wouldn't remove any old documentation from confluence or modify our site. > > > > Are there better options? > > > > Best, > > > > Tim > > >
