I've not being following this list too closely, so forgive me if this has been discussed before. Here's a simple suggestion that maybe could improve D docs a bit.

Perhaps, psychologically, the worst about the docs is that the function signature is used as a kind of section title. What about just reordering things a bit? Something like:

------

**startsWith**  [this is the title, rendered in some very prominent way. Just the function name, no parameters or anything else]

*Examples:*
// ...    [the examples section we already have today.]

*Detailed description*:  [the complete docs, as we have today]

-----

I believe the examples would do a better first impression than the full function signature, with all runtime and template parameters. I guess most people searching just want to see how to use the thing in the simplest cases anyway.

This could be improved in many ways. I actually started to write some other suggestions, but then gave up. My strongest point is that just reordering the things could be a way to improve the perception of D with minimal effort.

Cheers,

LMB
 






On Fri, Mar 13, 2015 at 12:17 PM, Andrei Alexandrescu via Digitalmars-d <digitalmars-d@puremagic.com> wrote:
On 3/13/15 7:51 AM, Chris wrote:
On Friday, 13 March 2015 at 14:34:23 UTC, Russel Winder wrote:
On Fri, 2015-03-13 at 14:20 +0000, Chris via Digitalmars-d wrote:
[…]

reluctant to learn something new. Crowd 2. we can win over, yet we
have failed to communicate with them, to reach out to them. Most
people I know have a look at D's homepage and say "Uh! Hm. Ah, I'll
use Python." No, they are not hardcore programmers, they are
engineers and scientists. But they are _users_, people who need to
write software to analyze data, to create something. We should not
ignore them, even if they are not (initially) interested in templates
and metaprogramming. Neither was I, when I first learned D.

It is not Python or R or Julia the language that people choose, it is
the superstructure built on top. So for Python, it is Pandas,
Matplotlib, SciPy, NumPy. And the ability to use ready made C, C++ and
Fortran libraries.

Exactly, that's part of it. People don't understand that they can use
all the C libraries with D as well. And if they do, "extern (C)" is too
"complicated", at least more complicated than "import numbergrind". I'm
really at loss here, I don't know how to communicate these things to
people. Colleagues and text books that talk about R and Python weigh so
much more than "D can actually interface to C without any effort".[1]

Also, sometimes I have the impression that people use any excuse not to
use D.

 That may as well be basic psychology at work. Curb appeal (or lack thereof) is difficult to explain but is easy to rationalize with unrelated arguments.

There is something loosely related to curb appeal that has been discussed here before. Consider someone just starts with D and wants to figure whether there's a startsWith function in D.

So they google for something like ``dlang startswith''. Nicely enough http://dlang.org/phobos/std_algorithm.html comes up first. (Ideally the individual page http://dlang.org/library/std/algorithm/starts_with.html would come up.)

Anyhow, assuming the user clicks on the former, startsWith is easy to find at the top and then when you click on it...

====
uint startsWith(alias pred = "a == b", Range, Needles...)(Range doesThisStart, Needles withOneOfThese) if (isInputRange!Range && Needles.length > 1 && is(typeof(.startsWith!pred(doesThisStart, withOneOfThese[0])) : bool) && is(typeof(.startsWith!pred(doesThisStart, withOneOfThese[1..$])) : uint));
bool startsWith(alias pred = "a == b", R1, R2)(R1 doesThisStart, R2 withThis) if (isInputRange!R1 && isInputRange!R2 && is(typeof(binaryFun!pred(doesThisStart.front, withThis.front)) : bool));
bool startsWith(alias pred = "a == b", R, E)(R doesThisStart, E withThis) if (isInputRange!R && is(typeof(binaryFun!pred(doesThisStart.front, withThis)) : bool));
====

This in big bold font, too. The HTML way of saying, "you wanted startsWith? I'll give you more startsWith than you can carry." Picture the effect this has on someone who just wanted to see if a string starts with another.

We need to make the template constraints distinct for formatting in ddoc.

Sadly http://dlang.org/library/std/algorithm/starts_with.html is bad in other ways. It doesn't have any examples! In contrast, the unified page does have some decent examples.

This all is under the "curb appeal" category.


Andrei