[
https://issues.apache.org/jira/browse/KAFKA-2967?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15050416#comment-15050416
]
Ewen Cheslack-Postava commented on KAFKA-2967:
----------------------------------------------
{quote}
The big problem with the existing docs is that many areas are poorly covered or
confusing or out of date. Personally, I think this is secondary to the
formatting engine. I think improving the formatting engine could make things as
much as 10% better but it could also make the resulting docs a lot worse if it
changes how they're integrated into the site.
{quote}
1. I think you're drastically overestimating the current user experience with
the docs. People might use the docs more if they were, you know, formatted so
they were usable. People that say Kafka has great documentation are referring
to a couple of very specific sections.
2. The choice of markup is rarely about directly improving the user's
experience. It's about making the technical writing process more efficient.
3. In the current state, it is so painful to edit docs that getting any edits
is like pulling teeth. The issues range from things that are definitely our
fault (I can't use a reasonable IDE or editor that handles HTML well, even just
emacs, not because the content is in HTML but because we are missing so many
closing tags that autoformatting is absolutely unusable) to limitations of the
markup language (including any code examples that use generics is an exercise
in frustration as you waste a ton of time replacing < > with HTML entities, all
the while rendering the raw text in your editor utterly unreadable or litter
CDATAs all over the place) to somewhere in the middle (super wide page with
scroll bar on the page instead of on a few divs that overflow; inconsistent
formatting of code/CLI snippets; manually updating the table of contents).
4. The goal of replacing the markup isn't to directly get that 10% benefit for
users. It's to make it easier for people to write docs so that we might
actually get those poorly covered or confusing or out of date sections in good
shape. I can tell you for sure that the Kafka Connect docs would have more
complete content if I hadn't wasted so much time with the markup.
5. I strongly believe docs contributions should be a requirement with patches
when there's something relevant to be changed, especially in a project like
this (it's not always feasible if docs can't be tightly integrated with the
code repo). In today's state, I couldn't ask contributors for that with a
straight face.
{quote}
The docs should stay part of the main site in styling, nav, etc. Doc things
like sphynx that dump you into a whole different site with different nav and
theming is just a terrible experience.
{quote}
So first, you might want to read up on the tool before making statements like
this. Nothing you said about Sphinx is accurate. You can style it however you
like, you can use an existing layout, it doesn't require you to generate a
separate site from your main site, it doesn't require a separate nav system.
You can use it to migrate from plain HTML content into its system if you want
(you can embed raw html easily). You can also generate only some pages of your
site with it without the user being able to tell.
That said, I think integrating the site and *all* the documentation, and trying
to use a single nav doesn't work well. It clearly doesn't work today since we
really have 2 navs -- one main one, which happens to link to a few sections of
the docs, and then the docs one, which is actively hurting the usability of the
docs because it's a ginormous TOC at the top of the docs page (scroll 1...,
2..., 3..., ahh, and now at the 4th page down I can finally see content).
{quote}
The output should look no worse than it currently does. That restructured
text page looks like it was imported from 1997. Hopefully that is not
indicative?
{quote}
Gwen specifically mentioned using ReST for markup and Sphinx to render it in
the JIRA. You're looking at a default minimalist docutils rendered ReST page. I
can make HTML and Markdown look like that page too. In fact, that's basically
what the Kafka docs page currently looks like... The goal of most of these
markup languages is to separate content from style.
{quote}
An easier approach might be to use something like Jykell that would allow us to
take what we have as is, and move to markdown bit-by-bit as a convenience; it
also allows you to fall back to html wherever needed and makes live preview
fairly easy to set up.
{quote}
1. I agree evaluating different options and the tradeoffs is a good idea. But
in practice, these things usually end up with 1 person really making the
decision because they were the only one who was willing to step up and take on
the project.
2. Migration cost for anything other than docs seems like a minimal issue. All
the overhead is in the docs since they account for close to 90% of the website
(although that includes autogenerated config docs).
3. Having used Jekyll myself, it may not add enough to address the current
frustrations with writing docs. One of the benefits of writing docs in a tool
designed around docs is that it applies the right constraints and provides the
right support to make writing docs easy.
All this said, I don't strongly favor Sphinx/ReST over other systems and I
definitely have plenty of complaints about it (e.g. the way links/references
work, or in some cases don't). So I'll just put my vote in for LaTeX.
> 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
>
> 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
(v6.3.4#6332)
