18

While going through the proposed edits, this topic change proposal in Installing Java (Standard Edition) sparked controversy in me:

  • it does not have code - does not seem fit on 'Doc
  • it is is high quality and rather useful - real value --> good
  • topic is related to coding - good
  • topic can not be illustrated through examples - unfit

I dumped it on the 'Doc chat too, and it was confirmed to be a controversial situation.

What is the way to go?

  • Allow codeless, and retain useful
  • Throw away value, but stay code only

(My personal view would be to allow such, as long as it has value for a developer.)

4
  • did you consider adding code of shell / bat scripts that install current version JDK on Linux / Windows? (probably Open JDK because messing with license stuff of Oracle JDK makes scripts complicated)
    – gnat
    Commented Aug 2, 2016 at 21:39
  • @gnat I had concerns regarding the topic itself, so I first wanted to clarify if that is even fit for the site, and if it is, in what form.
    – ppeterka
    Commented Aug 3, 2016 at 6:37
  • Isn't that topic a semi-duplicate of the example Installing Java Development Kit under Compile and run your first Java program which has had 30 contributors? Commented Aug 3, 2016 at 18:21
  • @JonnyHenly Well, even that... However, I'd rather have the installing part separate from any coding topic - if we must have it at all.
    – ppeterka
    Commented Aug 3, 2016 at 21:03

2 Answers 2

34

Installing the platform seems like a reasonable topic. But...

...The examples should actually demonstrate how to install Java. Right now, this is just a grabbag of information that... Is relevant to installing Java SE, but doesn't actually demonstrate anything.

The "What do I need for Java Development?" example is also somewhat opinionated, with bits like, "However for serious development work it is recommended that you also use the following". Not necessarily a show-stopper if there was more to it, but... That's all it is: someone's list of "serious Java tools".

I believe we should strive to be practical first, adding guidance and opinion only as it supports practical use. Right now, this topic does not do the one thing it purports to do: tell me how to install Java. And the proposed edits do nothing to remedy this.

9
  • And what is your opinion, could it be salvaged by renaming it to something more appropriate?
    – ppeterka
    Commented Aug 2, 2016 at 21:17
  • What is the value of it right now? What are we trying to salvage?
    – Shog9
    Commented Aug 2, 2016 at 21:22
  • @Shoq9 IMHO If I was to develop Java, but without experience, I feel that having that information on one page would give me relevant knowledge, like the tools in the JDK, the "What I need" kind of stuff. But this is kind of subjective, and this gray area...
    – ppeterka
    Commented Aug 2, 2016 at 21:25
  • So, you want a "what do I need" topic then?
    – Shog9
    Commented Aug 2, 2016 at 21:26
  • @Shoq9 I can use topic requests myself. I was asking if this is kind of topic useful/welcome at Documentation.
    – ppeterka
    Commented Aug 2, 2016 at 21:33
  • 10
    Right now, I'd say no. Have a look at the request that motivated the creation of this topic - note how of the 7 areas requested, only the first two are covered... Speaking as someone who was already thoroughly sick of dealing with this crap back when Sun owned it, this sort of impractical fixation with trivia over practical examples of how to actually get the damn thing installed seems utterly unhelpful.
    – Shog9
    Commented Aug 2, 2016 at 21:39
  • @Shog9 I think it should contain both things … that "trivia" and the actual installation… But yeah, significant points of that list are missing. Perhaps one also should be able to create a real list when requesting a topic and the creator of the topic shall then tick the done points and the other points get moved to different newly created improvement flags.
    – bwoebi
    Commented Aug 2, 2016 at 23:19
  • 5
    The trivia might be a lot less trivial if there were actual instructions to draw on it, @bwoebi. But there aren't. So...
    – Shog9
    Commented Aug 2, 2016 at 23:23
  • I totally agree. I believe it could be fit if integrated things like actual commands to set up a development environment in various OSes and configurations (e.g. how to setup Oracle java JRE/JdK in Ubuntu using update-alternatives and make sure that OpenJRE/JDK updates wont change the chosen alternative...)
    – Bakuriu
    Commented Aug 3, 2016 at 9:05
7

My opinion is that documentation about a language, like Java, should only show off language features, syntax, available API methods, and basic usage.

Showing someone how they can become a Java developer by setting up a development environment has nothing to do with the language, the specification, or the features of that language.

While setting up the development environment is crucial, it's more of a tutorial, and less of actual Java documentation.

My view is that it's not appropriate for SO Docs.

2
  • 3
    Tools for development are on-topic at SO. Commented Aug 3, 2016 at 18:45
  • 4
    You're right that it's not "Java language documentation". It is "Oracle Java Development Kit" documentation.
    – Ben Voigt
    Commented Aug 3, 2016 at 18:49

Not the answer you're looking for? Browse other questions tagged .