[
https://issues.apache.org/jira/browse/CASSANDRA-14313?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16398848#comment-16398848
]
Jon Haddad commented on CASSANDRA-14313:
----------------------------------------
{quote}
For some reason I'm told by many committers that we should not have sets of
documentation for other versions than the current version in a tree for that
version.
{quote}
True, we ship the docs that correlate to the version that's released.
{quote}
This has made it difficult, maybe impossible to have documentation for all the
supported versions on the website at one time.
{quote}
This isn't true at all. The docs for each version need to be built and put in
a directory for each version on the site repo itself. That's a normal build
process. The links for nav / etc need to be updated to support multiple
versions. The site is here: https://svn.apache.org/repos/asf/cassandra/site
{quote}
Maintain the code in html, css and javascript so changes can be made easily
using any number of programs.
That we immediately copy the current code to a new repository, convert it to
html, css and javascript, convert it into a multi-version form and then switch
over to it from now on for the online documentation.
{quote}
Absolutely not. Having the docs in sphinx means they are based on templates
and can be easily rebuilt. This is a solved problem already for a million
projects, regressing to manually editing HTML / CSS / JS would be a massive
waste of time and doesn't help anyone.
I'm a firm -1 on this. I've built docs out for a number of projects over the
years. This isn't the best set of docs, but certainly not the worst. If
anything we could move to a better toolset (hugo for everything), but making
everyone work with HTML / CSS / JS isn't going to get the docs any more
attention than it does now.
> Maintain a separate repository for the online documentation
> -----------------------------------------------------------
>
> Key: CASSANDRA-14313
> URL: https://issues.apache.org/jira/browse/CASSANDRA-14313
> Project: Cassandra
> Issue Type: Improvement
> Reporter: Kenneth Brotman
> Priority: Major
>
> For some reason I'm told by many committers that we should not have sets of
> documentation for other versions than the current version in a tree for that
> version. This has made it difficult, maybe impossible to have documentation
> for all the supported versions on the website at one time.
> As a solution I propose that we maintain the online documentation in a
> separate repository that is managed as the current repository under the
> guidance of the Apache Cassandra PMC (Project Management Committee); and that
> in the new repository we:
> # Maintain the code in html, css and javascript so changes can be made
> easily using any number of programs.
> # That we immediately copy the current code to a new repository, convert it
> to html, css and javascript, convert it into a multi-version form and then
> switch over to it from now on for the online documentation.
> I ask you to consider that right now there is not much on the web site. Many
> of us have the skill set to do this work in a matter of days. I can myself.
> Therefore, if this is agreeable to everyone, whether no one else helps or
> not, I will make sure its done over a two week period of time.
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
