For the Love of God, Please Write Better Docs!

[Jack Stouffer via Digitalmars-d]

Warning, rant ahead.

I was trying to replicate asyncio Python functionality in D for a 
script that needs some updating at work. I got inspired after 
attending many talks and demos on the subject of async network 
requests and disk IO at the PyOhio conference this past weekend. 
I wanted to see if D was up to the task in part of my continuing 
crusade to introduce D at my place of work. I just spent the last 
five hours on this with no success and I give up; I'm just going 
to rewrite the original script in Python3.

I tried writing the functionality in libasync[1] and the higher 
level asynchronous[2] (not trying to pick on anyone, this is just 
my experience). libasync has no online docs, which makes the 
thing DOA for me. Regardless, I pushed on and got to the first 
step with libasync's examples, but it didn't have some of the 
higher level constructs that asyncio has, so I turned to 
asynchronous, which seems to be a D port of Python's asyncio.

It has online documentation of all of the functions and classes, 
great! But, the "examples" consist of the contrived tests and 
don't show real usage. Imagine you just bought a piece of 
furniture from Ikea, you have your toolbox and all of the parts 
out, but someone forgot to include the instruction manual in the 
box. You're smart enough to get the general shape of a dresser, 
but it collapses under it's own weight because you really don't 
know what you're doing. Or imagine trying to write a Java app in 
a world where Design Patterns never existed. That's what working 
with that kind of documentation is like. I can't for the life of 
me figure out how any of these pieces fit together, so I'm 
dropping it.

So please, if you don't want your hard work to go to waste, and 
you want people to use your library, please put more effort into 
better documentation. I love D, but I don't have the time to put 
more trial and error into this. I could read the source of the 
various libraries, I could continue banging my head against this 
wall, I could write my own code from the ground up using just the 
fiber interface. But at the end of the day, I need results, and 
I've already spent too much time on this.

Things that make "good" documentation:
1. A description of the possible uses of the library, and what 
you shouldn't use it for
2. The docs need to be accessible, that means having it online 
and searchable.
3. Detailed descriptions of the parameter and return values
4. If something will throw, say what will throw and when
5. Descriptions of other ways you might be shooting yourself in 
the foot. For example, documentation of alloca should warn about 
what happens when the current stack frame is left
6. Examples for every function. Simple examples are nice, but an 
example which shows real world use is even better. You need to 
show the user why this function exists.
7. Module level examples, meaning examples which show the entire 
module working in tandem. For example, the standard example for 
an async library is a async web crawler, which is a great way to 
show how to do something basic in concept while using a great 
number of features.

A great example of good docs are the docs for 
std.experimental.allocator[3]. It describes its goals, what it's 
for, and how to practically use it in a program. Each function 
has examples and parameter and return value descriptions.

[1]: https://github.com/etcimon/libasync
[2]: https://github.com/dcarp
[3]: https://dlang.org/phobos/std_experimental_allocator.html