[DISCUSS] Move to in-repo asciidoc for 4.x?

[Tim Allison <ta...@apache.org>]

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

Re: [DISCUSS] Move to in-repo asciidoc for 4.x?

[Tim Allison <ta...@apache.org>]

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 <ol...@gmail.com>
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 <ta...@apache.org> 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
> >
>

Re: [DISCUSS] Move to in-repo asciidoc for 4.x?

[Oleg Tikhonov <ol...@gmail.com>]

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 <ta...@apache.org> 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
>