[
https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17697870#comment-17697870
]
Tom Bentley commented on KAFKA-2967:
------------------------------------
Thanks for taking a look at this [~jeqo].
The multi-page approach definitely does have significant benefits, but it would
break all existing deep links into the docs. I think it would be worth going to
some effort to avoid that. So I'd be interested to know if we could redirect
{{/documentation#fragment}} to the right new page
{{{}/documentation/whatever#fragment{}}}.
On the subject of markdown vs asciidoc: If we're counting people's stated
preferences upthread then it looks like 2:1 in favour of asciidoc. My
experience with markdown is that it's just not quite fully-featured enough for
technical documentation and over time that often leads to people layering-on
plugins and/or JS hacks, at which point it becomes a poorly-specified
"markdownish", but not markdown. Asciidoc supports all the things you're likely
to need using a single, well-documented syntax.
However, the perfect is the enemy of the good. I'd be delighted to stick with
markdown if it results in a better authorship experience in the short term.
Using pandoc I suppose we could relatively easily switch the docs to asciidoc
in the future if we felt that markdown was too limited.
> Move Kafka documentation to ReStructuredText
> --------------------------------------------
>
> Key: KAFKA-2967
> URL: https://issues.apache.org/jira/browse/KAFKA-2967
> Project: Kafka
> Issue Type: Bug
> Reporter: Gwen Shapira
> Assignee: Gwen Shapira
> Priority: Major
> Labels: documentation
>
> Storing documentation as HTML is kind of BS :)
> * Formatting is a pain, and making it look good is even worse
> * Its just HTML, can't generate PDFs
> * Reading and editting is painful
> * Validating changes is hard because our formatting relies on all kinds of
> Apache Server features.
> I suggest:
> * Move to RST
> * Generate HTML and PDF during build using Sphinx plugin for Gradle.
> Lots of Apache projects are doing this.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
