[jira] [Commented] (FLINK-3132) Restructure streaming guide

["ASF GitHub Bot (JIRA)" <ji...@apache.org>]

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

ASF GitHub Bot commented on FLINK-3132:
---------------------------------------

GitHub user uce opened a pull request:

    https://github.com/apache/flink/pull/1499

    [FLINK-3132] [docs] Initial docs restructure

    This PR restructures the documentation by allowing pages with sub-navigations and furthermore fixes some minor issues and adds small utilities.
    
    A preview can be found here: http://uce.github.io/flink
    
    The goal of the changes is to increase readability in terms of structure and layout. The content has not been touched (except for minor things like typos etc.)
    
    ## Main Changes
    
    ### Streaming and Batch Guide
    
    The links under `Programming Guides` were intermixed with both streaming and batch docs, for example we currently have the following mixed points: `DataSet API`, `DataStream API`, `Python API`, `Fault Tolerance` (for both streaming and batch), `State in Streaming Programs`, `Interactive Scala Shell`, `DataSet Transformations`, etc. This was kind of confusing. With this PR, the streaming and batch docs have been grouped to a `Streaming Guide` and `Batch Guide` respectively.
    
    ![screen shot 2016-01-12 at 14 35 10](https://cloud.githubusercontent.com/assets/1756620/12264845/bc5e30b2-b939-11e5-8bf4-5923689e3245.png)
    ![screen shot 2016-01-12 at 14 35 16](https://cloud.githubusercontent.com/assets/1756620/12264846/bc804198-b939-11e5-8fc2-d42b61d10aa5.png)
    ![screen shot 2016-01-12 at 14 42 18](https://cloud.githubusercontent.com/assets/1756620/12264999/b7213968-b93a-11e5-9c58-efc8e66a049f.png)
    
    The respective links have been removed from the top level navigation. If you look at the preview, open the programming guides drop down and compare.
    
    Futhermore, it's now very easy to add new top level or sub level elements (see `README.md`).
    
    ### Layout changes
    
    Some people complained that the text was too small. This has been addressed and the per page table of contents has been narrowed down a little as well. The default text is now a little larger. An issue with the responsiveness (where the top level elements would wrap a line) has also been addressed.
    
    ### Removed content
    
    Removed the TEZ guide, and HDFS and SSH setup instructions from the cluster setup guide. I would like to remove the bundled examples page from the Batch guide as a follow up as well.
    
    ## Follow Ups and Know Issues
    
    There are plenty of follow ups, which I would like to file JIRAs for after this is merged.
    
    - Improve getting started guide on the front page
      - Simplify stack figure (Remove embedded, Tez, Optimizer, Stream Builder)
      - Guide the user to interesting pages
    - Improve quick starts (ready to run packages, demo scripts, etc.)
    - Make docs streaming first (many parts treat batch first)
    - Fine-grained restructuring of streaming guide content (separate page for windowing, state, etc.)
    - Fine-grained review of content
    - Known Issue: Flink ML inserts some whitespace due to Latex scripts (?)
    - Known Issue: Check code example code style
    
    ---
    
    **The main question for this PR is whether you agree with the restructuring and layout. It would be great to merge this as soon as possible and then address all follow ups until the 1.0 release.**

You can merge this pull request into a Git repository by running:

    $ git pull https://github.com/uce/flink docs_restructure

Alternatively you can review and apply these changes as the patch at:

    https://github.com/apache/flink/pull/1499.patch

To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:

    This closes #1499
    
----
commit 35de514544fb1bdde13253283a6f35ee06b1af60
Author: Ufuk Celebi <uc...@apache.org>
Date:   2015-12-24T00:19:02Z

    [FLINK-3132] [docs] Initial docs restructure

----


> Restructure streaming guide
> ---------------------------
>
>                 Key: FLINK-3132
>                 URL: https://issues.apache.org/jira/browse/FLINK-3132
>             Project: Flink
>          Issue Type: Improvement
>          Components: Documentation
>    Affects Versions: 0.10.1
>            Reporter: Ufuk Celebi
>            Assignee: Ufuk Celebi
>             Fix For: 1.0.0
>
>
> The streaming guide is in parts very cluttered and overloaded.
> I think it needs a restructuring and de-cluttering by splitting it up into multiple pages.
> This will make it easier to navigate to the relevant parts of it. It will also improve the custom search. At the moment you often end up on the single long page streaming guide, where you still need to find it manually.
> Some introductory notes about the main concepts are missing as well.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)