Documentation Improvement Initiative

[Daren Scot Wilson]

On Monday, 17 February 2020 at 15:09:39 UTC, bachmeier wrote:
> On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
>> This thread is a place to collect your documentation pain in 
>> one place.
>
> I once tried to use std.socket:
> https://dlang.org/phobos/std_socket.html
>
> Although it does link to a couple of examples, they don't have 
> any explanation, so I gave up. An example where you're up and 
> running in five minutes using Dub would be really nice. It's 
> pretty clear that the documentation for std.socket assumes the 
> user has learned sockets programming in another language before 
> coming to D. We should remove that prerequisite.


I am exactly such a person today!  The last time I did anything 
with sockets was 15 (?) years ago, and was very basic, and only 
for part of one day.

This week, I wanted to toss together a quickie tool to send some 
test data in binary over UDP to another machine.  I had to forget 
about the "quickie" part of that.

All the info I need about D and its libraries is there, but often 
details are hard to find if I don't already know the name of the 
module to look in. More examples would help. Just basic usage 
examples, not too basic, but enough to do something simple.

Running off somewhere else to learn UDP sockets in C or Python or 
whatever then coming back isn't my idea of efficiency.  Would-be 
users of D coming from science, engineering, fine arts, 
economics, robotics, or wherever, are likely to be interested in 
the good features of D but unlikely to want to learn another 
language to understand some feature, such as sockets.

D documentation shouldn't try to explain these sorts of things 
from scratch, of course, but a few of the very fundamental ideas 
need to be shown in an example and a few words.