API Documentation Analytics

[itsjoeconway]

It'd be great to have traffic/analytics on API documentation pages. It could easily be public information. It would help track if people are using documentation, what parts of the documentation they are using most, etc.

[jonasfj]

Wouldn't this be extremely biased by what properties have good documentation?

I mean, I look at documentation for a class/property a lot if it is the only thing has an example... But that might not be because I need it to have better documentation.. I spend very little time looking at properties that only have a single line of documentation without an example or even an illustration of what the possible values could look like :)

Maybe we should add a "I feel confused" button to all documentation pages? Then you can click it to signal that you need better docs :) hehe

It's certainly an interesting idea... if we were to expose number of views, then how should it work across releases and versions, do you reset the counter?

[itsjoeconway]

I’m thinking more like just running an instance of google analytics. Being able to identify areas of opportunity: most used features might help development prioritization, documentation improvements can be made more easily, and generally you can understand how people are using your product. Side benefit: Dart developers are now exposed to another google tool to keep them in the ecosystem.

[jonasfj]

Hmm, if I asked users I suspect that few of them would view a the API reference for a package as an independent website. Because that's clearly not what it is, hehe...

So if we were to expose analytics to package owners on traffic patterns it would probably come as a surprise to users. If users are surprised (or have reason to be surprised) about how data is shared then we might have a privacy concern.

If we are to expose data about traffic we should do it publicly, and I'm not sure Google analytics is a good way to do that -- if it's even possible..

Maybe we could query Google analytics for a visits counter... It's not much, but still pretty cool. Like how at the bottom of every Wikipedia page there used to be a page view counter... It's still there hidden under page info it something -- but a simple page view counter might be good enough..

[isoos]

Being able to identify areas of opportunity: most used features might help development prioritization, documentation improvements can be made more easily, and generally you can understand how people are using your product.

I'm not entirely convinced that documentation traffic would help with that. I usually hit API documentation pages when I'm still exploring if a package provides the thing I'm looking for, or when something went terribly wrong and I try to figure out where I need to use a different thing. The items that are straightforward or "just work" (== the thing I actually use from a pacakge) won't be reflected in such traffic.

Instead, I'd probably encourage interaction on the package's issue tracker for getting feedback. Maybe a community feedback besides basics (e.g. likes, distrusts) could be part of the pub site, but I'd imagine it as a broader, cross-package wishlist, than a package-specific voting mechanism.

Having said that, maybe we should include the pub package page views and the API documentation views as part of the popularity metric?

[itsjoeconway]

I'm not really interested in popularity metrics. I'm interested in improving a product. We use Google Analytics to improve documentation already. For example, watching drop off rates on tutorials is a nice indicator of how long folks want to invest, how confusing the content might be, etc.

I'm honestly surprised there is this much pushback on the value of website analytics. It's probably easier to just deploy dartdocs to our existing website?

[isoos]

It's probably easier to just deploy dartdocs to our existing website?

I think it is unlikely that the pub site will provide documentation analytics anytime soon (higher priority items in the work queue), and if you think it helps you, self-hosting would be the way to go. Recent updates to dartdoc would allow you to customize the generated HTML files via dartdoc_options.yaml.

Once you have done that, you can use the documentation property in pubspec.yaml, and the pub site will display it as a link.

[sigurdm]

We could start considering this when we have the download counts in place.

Would be a cool feature, not sure of the priority