[ZEPPELIN-1644] make document easier to follow key instructions

[Leemoonsoo]

What is this PR for?

Doc should deliver key features and recommended usage more simple and easy way.

• docs/install/install.md has lots of duplicated section with README.md.
• docs/install/install.md includes install from binary as well as build from source. I've seen that makes some beginners try download binary and then source build it again.
• recommended and key usage need to be highlighted.
• Be less verbose in key instructions. Move optional, additional info from in the middle of key instruction to end of the each page.

What type of PR is it?

Improvement

Todos

• - improve doc

What is the Jira issue?

https://issues.apache.org/jira/browse/ZEPPELIN-1644

How should this be tested?

Run doc locally

Screenshots (if appropriate)

Questions:

• Does the licenses files need update? no
• Is there breaking changes for older versions? no
• Does this needs documentation? no

[Leemoonsoo]

cc @AhyoungRyu

[AhyoungRyu]

I can't find build.md file. Is this intended?

[tae-jun]

@Leemoonsoo Nice! When I was at Zeppelin meetup, every beginner tried to build Zeppelin. Because they didn't know about existence of Zeppelin binary :-)

So I suggest adding a link to http://zeppelin.apache.org/download.html on README.md instead of install, and make super big button for downloading Binary package with all interpreters on Download.html. Too many options make beginners confused 😄

What do you think?

And like @AhyoungRyu said above, install is invalid.

[AhyoungRyu]

@Leemoonsoo I've always thought that such long README.md makes the entrance barrier high so that beginner can't start Zepplin easily. Definietly better tha before. @tae-jun maybe the invaild snapshot link is related to #1616. Am i right?

[Leemoonsoo]

Pushed missing build.md.
Thanks @tae-jun @AhyoungRyu for the review.

I agree on improving download page, make sure using binary package as a first option, build from source is optional / or for development. Thanks for suggestion @tae-jun. While download page resides on gh-pages branch, i'll make a separate pullrequest after merge this PR.

[jfanegan]

As a newbie to Zeppelin and this being my first contribution (by the way,
I'm still unable to get Zeppelin installation on Window 7 to work properly.
When I start Zeppelin from Git or Cygwin, I get this frustrating, annoying
output: zeppelin process died [failed], and in the log file, Error: Could
not find or load main class org.apache.zeppelin.server.ZeppelinServer),

I'll suggest separating installation steps and requirements by OS
environment - both for binary package installation and for building from
source. There are issues with installing Zeppelin on Windows, hence the
reason why this guy built this product:
http://mund-consulting.com/Products/Sparklet.aspx. However, his product
doesn't have the latest release or all the interpreters installed - reason
why I'm still trying the installation.

It'd be nice to have beginner's videos on installing in each OS. I've seen
a video for Ubuntu installation, but none for Windows. None of the folks
that I know have been able to get this working on Window 7.

I don't know if this is right place for my comments, but apologies if it is
not..

On Wed, Nov 9, 2016 at 9:11 PM, Lee moon soo notifications@github.com
wrote:

Pushed missing build.md.
Thanks @tae-jun https://github.com/tae-jun @AhyoungRyu
https://github.com/AhyoungRyu for the review.

I agree on improving download page, make sure using binary package as a
first option, build from source is optional / or for development. Thanks
for suggestion @tae-jun https://github.com/tae-jun. While download page
resides on gh-pages branch, i'll make a separate pullrequest after merge
this PR.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
#1615 (comment), or mute
the thread
https://github.com/notifications/unsubscribe-auth/AQrA8PsMNcCiy061fJD1QM0_JsPPDuo4ks5q8otOgaJpZM4Ksxxa
.

[AhyoungRyu]

@Leemoonsoo There is one more good place to add the location of build.md : docs/0.7.0-SNAPSHOT/#quick-start. And LGTM :)

[AhyoungRyu]

@jfanegan Thanks for sharing your issue and considerate feedback as well. Yeah it makes sense. I've also seen many Windows users struggling with Zeppelin installation with various error cases.
How about creating a new Jira ticket for this? You can create it in here: https://issues.apache.org/jira/browse/zeppelin. Then the title can be "Separating installation steps and requirements by OS environment" as you said.

[Leemoonsoo]

@jfanegan Thanks for the feedback and suggestion. We can address that in the other issue.

@AhyoungRyu @tae-jun Thanks for the review and merge to mater if there're no further comments.