digitalmars.D - For the Love of God, Please Write Better Docs!
- Jack Stouffer (61/61) Aug 02 2016 Warning, rant ahead.
- Adam D. Ruppe (9/10) Aug 02 2016 libasync is actually the one third party package I slapped on
- profan (13/21) Aug 04 2016 I can't agree more on the point of including examples of actual
- poliklosio (27/28) Aug 05 2016 I cannot agree more with that.
- H.Loom (16/47) Aug 05 2016 This is not true for widely used libraries. I can find everywhere
- poliklosio (11/42) Aug 06 2016 I think we agree here. Most libraries are marginal, and missing
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
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
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
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
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: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 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.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
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: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.On Tuesday, 2 August 2016 at 20:26:06 UTC, Jack Stouffer wrote: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.(...)(...) In my opinion open source community massively underestimates the importance of high-level examples, articles and tutorials. (...)Why the sarcasm? I was just venting (at no-one in particular) after hitting the wall for a large chunk of my life.If you are a library author and you are reading this, let me quantify this for you.Thanks you ! you're so generous.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.(...) 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 06 2016