Survey Results - When you read documentation on a new language, what's important?

Tell my why I should use this language over C++ and C#. If there's any good reason why I should use it, then the other stuff can follow. Otherwise I don't have the time.

In a non-hobbyist setting, that may be be important to you, your company or your customer(s). Frequently (maybe in most cases, this is strongly affected by factors unrelated to the technical language properties, and you are not likely to find it in the documentation on the language.

I've learned new languages: When the company decided to switch to a less used language to protect their IP rights in case the source code was stolen. When entering a new position, and a management decision had been made about language choice before I entered. When getting the responsibility for maintaining existing software in a language new to me. When the context, such as html, restricted the languages available. When a test framework was introduced where test procedures was written in a language new to me. When direct interface to hardware was required, so I had to learn another assembly language. When I had to modify the system build functionality of the 'editor' (well, some people say that emacs is a good OS, but it lacks a decent editor ...).

I have experienced all of these situations. I can imagine several others: A needed library may available only in a specific language (years ago, IBM had some great graphics software in APL). Your customer is buying the source code, dictating your language selection. Your team are experts in a domain specific language new to you. ... We could probably dig up a dozen other examples of restrictions not related to the language itself, but to your specific context.

The language documentation may of course boast: This is the perfect language for everything! without going into any specifics, or only things unrelated to your specific situation (such as 'You can program your editor's behavior', which is irrelevant if your editor is non-programmable or only in another language).

As a hobbyist, you have a great freedom to pick the language of your choice. A small one-man or few-men company restricted to a small class of software, such as small freestanding closed-source applications, interfacing with other software only through IP based protocols (or not at all) may have a similar freedom. And, you have the freedom to shy away from employers expecting you to program in languages other than those you already know.

I fully agree, although I'm pretty sure of the answer most of the time (it isn't better than C/C++, for me).
But recently I'm looking for a good scripting companion to the holy trinity (asm/C/C++) and I found that Julia fills in pretty much those requirements (although in contrast to Python, this language has a huge list of dependencies). I'm always looking for performance and efficiency over ease of use, so the fact that Julia is precompiled (kinda), natively has parallelism (finally) and has basic datatypes (I still can't figure out why anyone could ever want magical-all-in-one-variables, pointers solve everything otherwise).
The languages that remind us of how a computer works are always the good ones. Readability be damned.

Cool, someone who gets it. So Julia:

Is a good scripting companion to the holy trinity (asm/C/C++)
Has performance and efficiency
Is precompiled
Natively has parallelism
Has basic datatypes

You missed out this little detail, which is highly important to me:

Julia has a C API, so is callable from C++, C#, Python, etc

Alright! That's the most important information I need. I now know that stuff can be written in Julia, it will be performant, and it can be plugged into our C# (GUI/Database/Networking), C++ (data models, calculations), CUDA (GPU compute), Python (user scripting) monolith.

Now I can look at that secondary stuff as it's passed the first hurdle.

Well, C++ and C# are powerful but complex languages which lean on huge frameworks.

Sometimes snappier, less powerful languages have their right to be - despite its many issues I still mourn Visual Basic the First because writing testers, simple forms and basically oversized scripts was a breeze.

I found it especially useful to interact directly with DLLs and/or hardware devices, much better than writing a CLI - with a handful of textboxes, a combobox and a few buttons you could test any input to any function and visually show a comprehensive state of the system.

GCS d--(d-) s-/++ a C++++ U+++ P- L+@ E-- W++ N+ o+ K- w+++ O? M-- V? PS+ PE- Y+ PGP t+ 5? X R+++ tv-- b+(+++) DI+++ D++ G e++ h--- r+++ y+++* Weapons extension: ma- k++ F+2 X

I sometimes mourn the original BASIC ROMS that came on home PCs. It was nice to turn on an old computer and be immediately greeted with a BASIC prompt. You could type:

10 PRINT "Hello World"
20 Goto 10
Run

and Hello World would scroll forever.

I agree, that was wonderful.

But in reality those computers were just toys compared to the modern desktop PC.

The difficult we do right away...
...the impossible takes slightly longer.

I also like C# a lot, but there is no such thing as the best or universal programming language for everything. It always depends on the project and the goal of the solution. The possible paths to the goal are always influenced, shown and limited by the resources that are available.

As mentioned by others, it's not always about performance and efficiency. Often other things get a higher priority, like the target market and customers, or the required compatibility and usability of libraries, tools, or a special environment.

The languages C++/C# certainly ask for good possibilities for desktop or client software projects, but in other areas this is usually not a good choice. To give just a simple counter-example that everyone knows, well-known things are mostly well represented on the web for client/server solutions. For the client, JS (with HTML/CSS) leads, and for servers (outside of cloud solutions) it is still the good old all-rounder PHP.

That is why I am always open to other languages, and I choose what helps best and brings the project work to its goal in the best way.

Something about which we often break our head:
"In the name of the Compiler, the Stack, and the Bug-Free Code. Amen."
(source unknown)

I mostly want step by step instructions on how to configure the working environment. And after it the explanation of what and why is needed, and how those are connected.

Option	Votes	1	2	3	4	5
A comprehensive list of all the keywords, operators, built in functions and features of the language	570	6%	6%	18%	25%	44%
Comprehensive docs on the main / most common libraries used with the language	570	5%	10%	25%	32%	27%
Beginner tutorials	570	6%	9%	20%	25%	39%
Template apps to get me started	570	10%	15%	27%	28%	19%
Information on not just what things do, but why they do it	570	9%	16%	30%	27%	16%
Information on when to use certain functionality (not just that the functionality exists)	570	8%	10%	31%	32%	18%
A quick reference for everything. I just need a reminder on syntax / parameters	570	5%	6%	21%	29%	38%
Examples of how to deal with common errors	570	5%	8%	33%	34%	18%
Architecture Best Practices (how do I structure a new app properly?)	570	6%	11%	31%	26%	25%