[jira] [Commented] (IGNITE-7595) Find and switch to alternate documentation engine

["Denis Magda (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/IGNITE-7595?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16441620#comment-16441620 ] 

Denis Magda commented on IGNITE-7595:
-------------------------------------

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)