Lost a new commercial user this week :(

[Manu via Digitalmars-d]

On 19 December 2014 at 19:12, Walter Bright via Digitalmars-d
<digitalmars-d at puremagic.com> wrote:
> On 12/18/2014 2:24 AM, Manu via Digitalmars-d wrote:
>>
>> Docs need to have examples which are plain and obvious, and the
>> language will be absorbed by osmosis.
>
>
> I agree. Can you point to specific cases that need an example?

In this case, my colleague felt it was hard to understand the string
functions, but he got through it (after sending me txt messages to ask
questions).
I recall making the same comments when I first started trying to do
string manipulation in D. My personal take is, string functions are
all templates, which makes them look more complex than they are, and
for me, it was really hard to understand where to look for certain
functions; they're spread fairly evenly across 5 or so different
modules. Algorithm, range, ascii, uni, utf. Some of the most important
functions are in range and algorithm. Perhaps those that are fairly
string specific from range/algorithm should have aliases in
std.string, or std.string might public import some of the minor
modules, like ascii/uni/utf?

Like I said in the first post, documentation wasn't a deal breaker,
but it was the source of the most commentary. I think it's an area for
general improvement, and I would start by reconsidering the basic
formatting for reducing noise and improving clarity of the simple
details, while the advances and less important details (like
contracts) may fade into the background a little.

I think a good goal is:
At a glance, the function reference that stands out is the name,
summary, and what arguments it accepts. The next thing is the detail
for each argument and return value.
Template args, which throughout phobos are rarely of any 'functional'
relevance, need to be toned down so they don't interfere with your
initial glance to understand the function and what it does.
Most of the time the template args are just some 'T', allowing the
function to work with multiple types - particular on strings and
algorithms. This is not particularly interesting information, and it
shouldn't distract from the important details.

Occasionally, there is a template arg that IS a relevant part of the
API... I'm not sure how this should be highlighted. Perhaps a subtle
visual distinction could be made for template args like 'T' which are
just used in the runtime arg list, and template args that don't appear
anywhere else, ie, they supply important function arguments. I think
there's probably room for some clever design in that space.

Finally, contracts are overwhelming, and it's also a feature of D that
nobody has seen before. When someone new to D encounters a contract in
the docs, they no longer trust their ability to usefully interpret the
documentation, and almost certainly become confused; nobody expects to
see an 'if' statement in a function declaration.
I think that's a shame. The contract usually has no impact on using
the function, or how it should be understood, is just applies some
limitations to it's genericity.
I think contracts should be disconnected and listed separately, as
additional information, or with some subtext that makes it obvious
what that often confusing bit of text actually means.

Ironically, the string and algorithm functions are probably the worst
offenders, but coincidentally, there is a high chance that these are
the first functions anyone will ever reach for, so they present a
terrible first impression.