[
https://issues.apache.org/jira/browse/THRIFT-4710?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16732252#comment-16732252
]
Randy Abernethy commented on THRIFT-4710:
-----------------------------------------
In my experience putting docs and code together is a good way of reducing
duplicate effort, keeping code/docs in sync and keeping related things in the
same place. These principles are the reasons for Javadoc, Pydoc, etc. The
humans create the docs as they code and commit both together and then the
automation renders the content into whatever format(s) required (html, pdf,
etc.).
I think the above suggestion of a single pull request is a really important
feature we should try to enable. The PR should include the code, the tests and
the docs.
Another thought is, as a developer, when I clone a repo, getting the code and
docs together is an uptick not an inconvenience. The MDs are small and there
should probably be only one/zero (readme.md?) per directory. I don't think
we'll need to worry about images as our doc images will be mainly code snippets.
My 2 cents
> Move all website content to markdown within the project
> -------------------------------------------------------
>
> Key: THRIFT-4710
> URL: https://issues.apache.org/jira/browse/THRIFT-4710
> Project: Thrift
> Issue Type: Documentation
> Components: Documentation, Website
> Affects Versions: 0.12.0
> Reporter: James E. King III
> Priority: Major
>
> Recent changes in Apache infrastructure has made it impossible to use the
> existing ASF CMS system to manage the Apache Thrift web site. We need to
> extract and move the content somewhere else. For reference, see:
> https://issues.apache.org/jira/browse/INFRA-17519
> This is a bunch of work nobody was expecting to have to do.
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
