[
https://issues.apache.org/jira/browse/HADOOP-11495?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14285405#comment-14285405
]
Steve Loughran commented on HADOOP-11495:
-----------------------------------------
APT was adopted, as recall, as it was what maven gave you. It wasn't that
anyone chose it deliberately: it was what there was.
Forrest, which renders very well into multiple formats, is superior to markdown
& APT for outputting to, say, PDF, but it's been an under-staffed OSS project
for a long time now, and while we use it for some of our site, that's it.
What does MD bring to the table?
# IDE support
# editors like Mou —this can render the content alongside the markdown
# tools to export MD from google docs &c
# Automatic rendering on github simply by pushing the artifacts. This is great
when developing your own branch on github: push and you can share the text, yet
it also works for ASF content that is mirrored
Best of all: anyone who knows markdown can edit the documents. We'll be
(hopefully) opening up editing to more people, hence (again, hopefully)
improving the quality of the docs.
Regarding all-or-nothing, you don't have to migrate 100% of the site in one go.
Sub-project-by-sub-project will work well.
One thing before applying it though: get pending doc patches in first.
> Convert site documentation from apt to markdown
> -----------------------------------------------
>
> Key: HADOOP-11495
> URL: https://issues.apache.org/jira/browse/HADOOP-11495
> Project: Hadoop Common
> Issue Type: Improvement
> Components: documentation
> Affects Versions: 3.0.0
> Reporter: Allen Wittenauer
> Attachments: HADOOP-11496-00.patch
>
>
> Almost Plain Text (aka APT) lost. Markdown won.
> As a result, there are a ton of tools and online resources for Markdown that
> would make editing and using our documentation much easier. It would be
> extremely beneficial for the community as a whole to move from apt to
> markdown.
> This JIRA proposes to do this migration for the common project.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
