<div dir="ltr"><div>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.<br><br></div><div>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:<br><br>------<br><br></div><div>**startsWith**  [this is the title, rendered in some very prominent way. Just the function name, no parameters or anything else]<br><br></div><div>*Examples:*<br></div><div>// ...    [the examples section we already have today.]<br><br></div><div>*Detailed description*:  [the complete docs, as we have today]<br></div><div><br>-----<br></div><div><br></div><div>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.<br></div><div><br></div><div>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.<br><br></div><div>Cheers,<br><br></div><div>LMB<br></div><div> <br><br></div><div><br></div><br><div><br><br></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Fri, Mar 13, 2015 at 12:17 PM, Andrei Alexandrescu via Digitalmars-d <span dir="ltr"><<a href="mailto:digitalmars-d@puremagic.com" target="_blank">digitalmars-d@puremagic.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">On 3/13/15 7:51 AM, Chris wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
On Friday, 13 March 2015 at 14:34:23 UTC, Russel Winder wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
On Fri, 2015-03-13 at 14:20 +0000, Chris via Digitalmars-d wrote:<br>
[…]<br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
reluctant to learn something new. Crowd 2. we can win over, yet we<br>
have failed to communicate with them, to reach out to them. Most<br>
people I know have a look at D's homepage and say "Uh! Hm. Ah, I'll<br>
use Python." No, they are not hardcore programmers, they are<br>
engineers and scientists. But they are _users_, people who need to<br>
write software to analyze data, to create something. We should not<br>
ignore them, even if they are not (initially) interested in templates<br>
and metaprogramming. Neither was I, when I first learned D.<br>
</blockquote>
<br>
It is not Python or R or Julia the language that people choose, it is<br>
the superstructure built on top. So for Python, it is Pandas,<br>
Matplotlib, SciPy, NumPy. And the ability to use ready made C, C++ and<br>
Fortran libraries.<br>
</blockquote>
<br>
Exactly, that's part of it. People don't understand that they can use<br>
all the C libraries with D as well. And if they do, "extern (C)" is too<br>
"complicated", at least more complicated than "import numbergrind". I'm<br>
really at loss here, I don't know how to communicate these things to<br>
people. Colleagues and text books that talk about R and Python weigh so<br>
much more than "D can actually interface to C without any effort".[1]<br>
<br>
Also, sometimes I have the impression that people use any excuse not to<br>
use D.<br>
</blockquote>
<br></span>
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.<br>
<br>
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.<br>
<br>
So they google for something like ``dlang startswith''. Nicely enough <a href="http://dlang.org/phobos/std_algorithm.html" target="_blank">http://dlang.org/phobos/std_<u></u>algorithm.html</a> comes up first. (Ideally the individual page <a href="http://dlang.org/library/std/algorithm/starts_with.html" target="_blank">http://dlang.org/library/std/<u></u>algorithm/starts_with.html</a> would come up.)<br>
<br>
Anyhow, assuming the user clicks on the former, startsWith is easy to find at the top and then when you click on it...<br>
<br>
====<br>
uint startsWith(alias pred = "a == b", Range, Needles...)(Range doesThisStart, Needles withOneOfThese) if (isInputRange!Range && Needles.length > 1 && is(typeof(.startsWith!pred(<u></u>doesThisStart, withOneOfThese[0])) : bool) && is(typeof(.startsWith!pred(<u></u>doesThisStart, withOneOfThese[1..$])) : uint));<br>
bool startsWith(alias pred = "a == b", R1, R2)(R1 doesThisStart, R2 withThis) if (isInputRange!R1 && isInputRange!R2 && is(typeof(binaryFun!pred(<u></u>doesThisStart.front, withThis.front)) : bool));<br>
bool startsWith(alias pred = "a == b", R, E)(R doesThisStart, E withThis) if (isInputRange!R && is(typeof(binaryFun!pred(<u></u>doesThisStart.front, withThis)) : bool));<br>
====<br>
<br>
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.<br>
<br>
We need to make the template constraints distinct for formatting in ddoc.<br>
<br>
Sadly <a href="http://dlang.org/library/std/algorithm/starts_with.html" target="_blank">http://dlang.org/library/std/<u></u>algorithm/starts_with.html</a> is bad in other ways. It doesn't have any examples! In contrast, the unified page does have some decent examples.<br>
<br>
This all is under the "curb appeal" category.<span class="HOEnZb"><font color="#888888"><br>
<br>
<br>
Andrei<br>
<br>
</font></span></blockquote></div><br></div>