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

On 3/13/15 8:37 AM, Chris wrote:
> Yep. This is part of the "make people feel good about it" approach.
> Plus, we're not selling shit, it's really a good product. In a way, we
> do it the other way around: bad marketing for a good product.

Yah, indeed. Continuing the experiment, I set out to find Go's startsWith. So I googled for ``startswith golang''. First hit is http://golang.org/pkg/strings/ but there's no StartsWith on that page. The second hit is http://stackoverflow.com/questions/13244048/no-startswith-endswith-functions-in-go, which puts me in the right direction - HasPrefix is the name. So I click on that and I get to http://golang.org/pkg/strings/#HasPrefix.

That has no example but the signature is obvious enough. Just to verify, I click on the "Example" link on the function "Index" below, and I edit these lines:

	fmt.Println(strings.Index("chicken", "ken"))
	fmt.Println(strings.Index("chicken", "dmr"))

to:

	fmt.Println(strings.HasPrefix("chicken", "chi"))
	fmt.Println(strings.HasPrefix("chicken", "dmr"))

Click Run produces "true\nfalse" and... I got it.

* * *

Now here's the interesting part. There's a world of difference between D's startsWith and Go's HasPrefix. (Not because there's anything wrong about HasPrefix.) It's just that startsWith is very powerful - disconcertingly so. It is quite literally the ultimate startsWith:

* Works with any combination of UTF8, UTF16, and UTF32.

* Works with not only strings, but any arrays

* Works with array and element (e.g. "abc".startsWith('a')), not only array and array

* Equality is too much? You can pass a predicate

* Efficiently looks for multiple prefixes in a single pass, e.g. "abc".startsWith("ab", '#')

* Scratch "array", works with any two ranges with comparable elements and for any range and comparable element

For example the expression (assuming s is e.g. a string)

  File("/tmp/a").byChunk(4096).joiner.startsWith(s)

opens a file, progressively reads chunks of 4KB, stitches them together at no cost, compares against a prefix until it makes a decision, then closes the file and returns the result. A putative Go user wouldn't even dream of using HasPrefix directly on a stream coming from a file; the whole endeavor would be a function that painstakingly takes all of these steps by hand.

We need to take the "disconcerting" out the documentation equation while still exposing the power. s1.startsWith(s2) is perfectly apt for two strings, and that should be immediately apparent to someone who just needs that.


Andrei

On 3/13/15 10:03 AM, Leandro Motta Barros via Digitalmars-d wrote:
> **startsWith**  [this is the title, rendered in some very prominent way.
> Just the function name, no parameters or anything else]

Yah, that'd be nice, and hopefully somewhat automatic with the new-style documentation page-per-function.

One issue I see here is that it's difficult to group together functions with slightly different names but related functionality (e.g. findSplit, findSplitBefore, findSplitAfter).


Andrei

On Friday, 13 March 2015 at 17:11:06 UTC, Israel wrote:
> Well see the real problem is that D cant seem to cater to one group or another.
> It cant cater to new/inexperienced people because it isnt portrayed that way.

I don't think D is a priori not suitable for  rookies. It just needs more paint. Just show me what Go has what can't be simple in D :)

> It cant cater to the hardcore/DieHard C/C++ people because it is difficult to convince them.

Or even impossible for some kind of personalities. C++ couldn't convince Linus to abandon C. Tell him about D then ;) I suggest to leave that type of people with their own toys. The better is going to win eventually.

> You need to pick a target audience and stick with it...

Or create multipurpose tool. I think D is the best multipurpose tool in the programming languages business. Of course D community doesn't have enough resources to produces high quality products on all fronts.

Number of resources is critical. D fights using its brilliance to overcome lack of resources. Go is on opposite position.

Piotrek

> Finally, I feel I should respond to this:
>
> On Friday, 13 March 2015 at 02:28:53 UTC, bachmeier wrote:
>> If you want to be Rob Pike Jr., Go is great. If you want to program your way, not so much.
>
> I have no reason to take this personally, seeing as I'm pretty
> secure in my non-Rob-Pike-ness, but from a product design (and
> selling) standpoint, blaming or insulting the user is, of course,
> missing the point. I felt equally put-off by the dismissive tone
> of some of the creators of Go towards those who "don't
> understand" Go's ethos. I still ended up using their language,
> but it wasn't for their persuasion skills. Thankfully, it seems
> this isn't the general tone of D's community, and the level of
> healthy, open debate over here appears to be much higher than for
> Go.


Sorry if it appeared I was being critical of you. I was only giving the reasons that I didn't like Go. Maybe I should have said Go forces you to program like Rob Pike. That works for a lot of programmers, but not for me.

I feel compelled to say that I don't represent the D community. Although I use D for work (https://bitbucket.org/bachmeil/dmdinline) I've never contributed anything to its development. I'm just a random guy on the internet that compared Go against D but came to a different conclusion.

On Friday, 13 March 2015 at 18:20:48 UTC, bachmeier wrote:
>> Finally, I feel I should respond to this:
>>
>> On Friday, 13 March 2015 at 02:28:53 UTC, bachmeier wrote:
>>> If you want to be Rob Pike Jr., Go is great. If you want to program your way, not so much.
>>
>> I have no reason to take this personally, seeing as I'm pretty
>> secure in my non-Rob-Pike-ness, but from a product design (and
>> selling) standpoint, blaming or insulting the user is, of course,
>> missing the point. I felt equally put-off by the dismissive tone
>> of some of the creators of Go towards those who "don't
>> understand" Go's ethos. I still ended up using their language,
>> but it wasn't for their persuasion skills. Thankfully, it seems
>> this isn't the general tone of D's community, and the level of
>> healthy, open debate over here appears to be much higher than for
>> Go.
>
>
> Sorry if it appeared I was being critical of you. I was only giving the reasons that I didn't like Go. Maybe I should have said Go forces you to program like Rob Pike. That works for a lot of programmers, but not for me.
>
> I feel compelled to say that I don't represent the D community. Although I use D for work (https://bitbucket.org/bachmeil/dmdinline) I've never contributed anything to its development. I'm just a random guy on the internet that compared Go against D but came to a different conclusion.

Ok, no worries.

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.

Ecosystems play a big role in language choice.

In our case, C++ has for a long time been pushed for plumbing at the OS level or that last performance that the JIT cannot help.

So any C++ replacement has to be able to be exposed as JNI, P/Invoke, COM, WinRT, V8.

As well as offer similar level of mixed debugging across boundaries.

On Friday, 13 March 2015 at 14:48:11 UTC, Andrei Alexandrescu wrote:
> On 3/13/15 1:53 AM, JN wrote:
>
> Then I tried Code::Blocks and the debug experience has been almost shockingly good. I had no idea! Then I found indeed a wiki page describing the features: http://wiki.dlang.org/CodeBlocks. It is easy to find via google by searching e.g. for ``ides for dlang''. But there is no obvious way to get there from dlang.org. I think we should feature the IDEs page more prominently.
>
>
> Andrei

There is a dead link on the CodeBlocks page, at the bottom of it :
http://j.imagehost.org/0768/codeblocks.jpg -> Should be replaced.

On 3/13/15 11:40 AM, ezneh wrote:
> On Friday, 13 March 2015 at 14:48:11 UTC, Andrei Alexandrescu wrote:
>> On 3/13/15 1:53 AM, JN wrote:
>>
>> Then I tried Code::Blocks and the debug experience has been almost
>> shockingly good. I had no idea! Then I found indeed a wiki page
>> describing the features: http://wiki.dlang.org/CodeBlocks. It is easy
>> to find via google by searching e.g. for ``ides for dlang''. But there
>> is no obvious way to get there from dlang.org. I think we should
>> feature the IDEs page more prominently.
>>
>>
>> Andrei
>
> There is a dead link on the CodeBlocks page, at the bottom of it :
> http://j.imagehost.org/0768/codeblocks.jpg -> Should be replaced.

Thanks for pointing that out. I've beat off all other eager volunteers with a stick, went to archive.org, retrieved the image, uploaded it to imgur, and linked it from the wiki.

http://wiki.dlang.org/CodeBlocks#Screenshot


Andrei

On 3/13/2015 3:34 AM, bearophile wrote:
> "Strict mode" is a D2 with immutable+@safe+pure by default,

Note that you can get this largely by starting a module with the following:

   immutable @safe pure:

> something like a "var" keyword to denote mutable values,

Transitive const may make this problematic.

> no comma operator,

Some good arguments for this.

> static full tracking of memory ownership,

Makes the language significantly more complex.

> less implicit casts (because now we have the safe int(x) sytnax),

I think D does very well with implicit casts.

> and few other small changes that make the language less bug prone and
> more strict.

> And I'd still like built-in tuple syntax in D.

[... Just one more feature ...] is the road to hell.