[ 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: # 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. 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. > 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)