www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - For the Love of God, Please Write Better Docs!

reply Jack Stouffer <jack jackstouffer.com> writes:
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
Aug 02 2016
next sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
On Tuesday, 2 August 2016 at 20:26:06 UTC, Jack Stouffer wrote:
 libasync has no online docs, which makes the thing DOA for me.
libasync is actually the one third party package I slapped on dpldocs.info: http://dpldocs.info/experimental-docs/libasync.html It is pretty minimal though, there aren't a lot of comments (I had to add a bunch just to get this much up) I'm not actually a user of that lib though, so I don't know it well enough to document it myself (I just put it on my site because someone else asked for the dox.)
Aug 02 2016
prev sibling next sibling parent profan <profan prfn.se> writes:
On Tuesday, 2 August 2016 at 20:26:06 UTC, Jack Stouffer wrote:
 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.
I can't agree more on the point of including examples of actual usage with your libraries, API docs in all their glory (which barely even exist for almost all D libraries in the wild as it is), examples help you actually understand how the pieces fit together. It could be as simple as having an examples folder with sample projects in it, or like in std.experimental.allocator, embedding the example usage within the API documentation. Either way, if anyone is interested in furthering D adoption, please include docs _and_ examples with your libraries. (hey, my first post on the forums!) Source code is not documentation.
Aug 04 2016
prev sibling parent reply poliklosio <poliklosio happypizza.com> writes:
On Tuesday, 2 August 2016 at 20:26:06 UTC, Jack Stouffer wrote:
 (...)
I cannot agree more with that. In my opinion open source community massively underestimates the importance of high-level examples, articles and tutorials. To most library authors (judging from projects I've seen) source code and reference docs is 90% of usability and everything else is 10%. This is completely wrong and upside-down! If you are a library author and you are reading this, let me quantify this for you. Influence of parts of documentation on usability: - Good tutorials and high-level examples for typical actual use-cases: 60% - Good README file with very clear instructions for installation and any other setup, e.g. interoperation with typical set of other libs: 25% - An article in prose explaining motivation for the library: 10% - Examples in online reference documentation: 3% - All the other elements reference documentation, source code readability: 2% This has no scientific basis, but I felt compelled to use numbers because words cannot illustrate the massive extent of the problem. Again, if you are a library author and you think this rant is silly then yes, your documentation is that bad. This also explains part of complaints on Phobos documentation - people don't get the general idea of how to make things work together. Those who do get the general idea don't care much about the exact width of whitespace and other similar concerns.
Aug 05 2016
parent reply H.Loom <loom grossnet.az> writes:
On Friday, 5 August 2016 at 19:52:19 UTC, poliklosio wrote:
 On Tuesday, 2 August 2016 at 20:26:06 UTC, Jack Stouffer wrote:
 (...)
I cannot agree more with that. In my opinion open source community massively underestimates the importance of high-level examples, articles and tutorials. To most library authors (judging from projects I've seen) source code and reference docs is 90% of usability and everything else is 10%. This is completely wrong and upside-down!
This is not true for widely used libraries. I can find everywhere examples of how to use FreeType even if the bindings I use have 0 docs and 0 examples. Idem for libX11...Also i have to say that with a well crafted library you understand what a function does when it's well named, when the parameters are well named. This is another story for marginal libraries, e.g when you're part of the early adopters.
 If you are a library author and you are reading this, let me 
 quantify this for you.
Thanks you ! you're so generous.
 Influence of parts of documentation on usability:
 - Good tutorials and high-level examples for typical actual 
 use-cases: 60%
 - Good README file with very clear instructions for 
 installation and any other setup, e.g. interoperation with 
 typical set of other libs: 25%
 - An article in prose explaining motivation for the library: 10%
 - Examples in online reference documentation: 3%
 - All the other elements reference documentation, source code 
 readability: 2%
congratz, you've taken care to reach exactly 100...
 This has no scientific basis, but I felt compelled to use 
 numbers because words cannot illustrate the massive extent of 
 the problem.

 Again, if you are a library author and you think this rant is 
 silly then yes, your documentation is that bad.

 This also explains part of complaints on Phobos documentation - 
 people don't get the general idea of how to make things work 
 together.
For phobos i agree. D examples shipped with DMD are ridiculous. I was thinking to propose an initiative which would be to renew completly them with small usable and idiomatic programs.
 Those who do get the general idea don't care much about the 
 exact width of whitespace and other similar concerns.
I don't understand your private thing here. Are you talking about text justification in ddoc ? If it's a mono font no problem here...
Aug 05 2016
parent poliklosio <poliklosio happypizza.com> writes:
On Friday, 5 August 2016 at 21:01:28 UTC, H.Loom wrote:
 On Friday, 5 August 2016 at 19:52:19 UTC, poliklosio wrote:
 On Tuesday, 2 August 2016 at 20:26:06 UTC, Jack Stouffer wrote:
 (...)
(...) In my opinion open source community massively underestimates the importance of high-level examples, articles and tutorials. (...)
This is not true for widely used libraries. I can find everywhere examples of how to use FreeType even if the bindings I use have 0 docs and 0 examples. Idem for libX11...Also i have to say that with a well crafted library you understand what a function does when it's well named, when the parameters are well named. This is another story for marginal libraries, e.g when you're part of the early adopters.
I think we agree here. Most libraries are marginal, and missing proper announcement and documentation is the main reason they are marginal. Hence, this is true for most libraries. Of course there are good ones, sadly not many D libraries are really well documented.
 If you are a library author and you are reading this, let me 
 quantify this for you.
Thanks you ! you're so generous.
Why the sarcasm? I was just venting (at no-one in particular) after hitting the wall for a large chunk of my life.
 (...)

 This also explains part of complaints on Phobos documentation 
 - people don't get the general idea of how to make things work 
 together.
For phobos i agree. D examples shipped with DMD are ridiculous. I was thinking to propose an initiative which would be to renew completly them with small usable and idiomatic programs.
 Those who do get the general idea don't care much about the 
 exact width of whitespace and other similar concerns.
I don't understand your private thing here. Are you talking about text justification in ddoc ? If it's a mono font no problem here...
I'm lost here. The "width of whitespace" was just an example of something you would NOT normally care about if you were a savvy user used who already knows how to navigate the docs.
Aug 06 2016