[
https://issues.apache.org/jira/browse/IGNITE-7595?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16441620#comment-16441620
]
Denis Magda edited comment on IGNITE-7595 at 4/17/18 10:51 PM:
---------------------------------------------------------------
Eventually, we'll give a try to Jekyll because it seems to be more flexible and
easy to use than Docusaurus.
Things to do next:
# Export readme.io content to markdown format using a script. The script has to
turn readme specific markdown (code, tables, etc.) to the standard one.
# The docs will be stored in {{docs}} folder of the main Ignite repository.
That's a standard approach adopted by Kafka, Spark, Flink, Cassandra, Storm and
other ASF projects.
# A future version of the docs will be stored in the master branch. Specific
branches will be used for specific documentation versions. If we'd like to
update docs of version X after Ignite X is released, then we create
"ignite-X-docs" branch after the release, make the changes there and regenerate
the HTML.
# Jekyll will be used to generate HTML pages from the markdown stored in Ignite
GIT repository. We can apply CSS and JS of our choice.
# HTML pages, CSS styles, and JS scripts are hosted on ignite.apache.org -
which is an SVN repository.
The following scripts are needed:
* Readme to the standard markdown (Jekyll) migration script.
* Script that calls Jekyll to generate the HTML then applies CSS and JS
snippets and then merges changes to Ignite site svn repository.
* An option to the script above that does all the same but for a subset of the
changes of a specific GIT commit.
* Script that will merge changes to the docs master and listed branches of
previous Ignite versions.
was (Author: dmagda):
Eventually, we'll give a try to Jekyll because it seems to be more flexible and
easy to use than Docusaurus.
Things to do next:
# 1 Export readme.io content to markdown format using a script. The script has
to turn readme specific markdown (code, tables, etc.) to the standard one.
# 2 The docs will be stored in {{docs}} folder of the main Ignite repository.
That's a standard approach adopted by Kafka, Spark, Flink, Cassandra, Storm and
other ASF projects.
# 3 A future version of the docs will be stored in the master branch. Specific
branches will be used for specific documentation versions. If we'd like to
update docs of version X after Ignite X is released, then we create
"ignite-X-docs" branch after the release, make the changes there and regenerate
the HTML.
# 4 Jekyll will be used to generate HTML pages from the markdown stored in
Ignite GIT repository. We can apply CSS and JS of our choice.
# 5 HTML pages, CSS styles, and JS scripts are hosted on ignite.apache.org -
which is an SVN repository.
The following scripts are needed:
* Readme to the standard markdown (Jekyll) migration script.
* Script that calls Jekyll to generate the HTML then applies CSS and JS
snippets and then merges changes to Ignite site svn repository.
* An option to the script above that does all the same but for a subset of the
changes of a specific GIT commit.
* Script that will merge changes to the docs master and listed branches of
previous Ignite versions.
> Find and switch to alternate documentation engine
> -------------------------------------------------
>
> Key: IGNITE-7595
> URL: https://issues.apache.org/jira/browse/IGNITE-7595
> Project: Ignite
> Issue Type: Task
> Components: documentation
> Reporter: Denis Magda
> Assignee: Prachi Garg
> Priority: Critical
> Fix For: 2.6
>
> Attachments: Docusaurus-GitBook comparison.docx,
> readme-markdown-mapping.xlsx
>
>
> Current readme.io documentation has many drawbacks that make the life of
> Ignite technical writers hard. Some of the problems are:
> * Each "version" is just a copy of the previous one. When fixing something,
> you have to update
> all the versions.
> * No good way to review changes.
> * "Propose edit" functionality is a not suitable for review. You can only
> accept or reject an
> edit, no way to communicate with a contributor, etc
> * There is no way to prevent Google from indexing old documentation
> versions. Thus, it's common to come across old doc version in a google
> search.
> We might consider GitHub based documentation or another approach. The
> discussion is here:
> http://apache-ignite-developers.2346864.n4.nabble.com/Move-documentation-from-readme-io-to-GitHub-pages-td16409.html
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
