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 > >
