search

ropensci-archive / roweb2

:no_entry: ARCHIVED :no_entry:
https://github.com/ropensci/roweb3
25 stars 72 forks source link

what belongs on Use Cases page? #73

Closed stefaniebutland closed 4 years ago

stefaniebutland commented 7 years ago

I see that Use Cases page says "examples on our most popular packages"

Do our > 10 blog posts on onboarded software count as use cases and should we add them? (they're not necessarily most popular pkgs)

Is this a place we could list citations of our packages e.g. those that @sckott collects for rOpenSci News e.g. https://ropensci.github.io/biweekly/update-2017-10-09/? Sets a great example showing people it's cool to cite software.

sckott commented 7 years ago

Yeah, it’s a bit confusing as that use cases page has code examples of using the packages while ropensci news use cases is simply list of papers/blog posts citing our packages

Open to what people want to see in a use cases page (or changing name if needed).

One direction is what GBIF does https://www.gbif.org/resource/search?contentType=dataUse where they do a tiny "blog post" about each paper using their data, e.g, https://www.gbif.org/data-use/Xnyomi8LIW8iewkkeYs66/tracking-free-roaming-cheetahs-outside-protected-areas-of-south-africa with a nice picture (since it's organism data, you can have a nice pic of an animal or so). We could do the same, in addition to code examples, or instead of perhaps.

We could just have a list of citations, though I think we can do better than that.

One downside to having these code examples is that we ideally should update them to make sure they work with the latest version of the package, which we haven't been doing.

stefaniebutland commented 7 years ago

Sounds like this page is one we need to think about. Maybe make it better in stages.

One direction is what GBIF does https://www.gbif.org/resource/search?contentType=dataUse where they do a tiny "blog post" about each paper using their data, ...

I know you've brought this up a few times Scott 😄 . The question is how much time is spent writing a short blurb vs value we get from it. Maybe we could do that for selected papers that are unique examples (for some definitions of unique) and list all other citations (cause that's a pretty powerful metric I think).

I'm too slow at blurbing to offer to do this. Are you keen on doing it Scott?

One downside to having these code examples is that we ideally should update them to make sure they work with the latest version of the package, which we haven't been doing.

Do you have time for that? "We" need to commit to checking them regularly if we're going to feature them.

Would we also list onboarding blog posts here? (I think so)

sckott commented 7 years ago

Would we also list onboarding blog posts here?

I tend to disagree, what's your reasoning?

Another reason to nix the code eg's on use cases page could be that we also have /tutorials, which demo the software and some of which have little use cases within them.

If we go this route of putting works citing our software on use cases page, i can attempt some GBIF like summaries, and see how it goes, I don't think i would do as much work as them. At a minimum it'd be nice to extract out what pkgs were used, and maybe a bit about for what purpose so people can get a sense of what our software is used for. And a pretty pic if possible 😸

stefaniebutland commented 7 years ago

I tend to disagree, what's your reasoning?

(naive here) What's the definition of Use Case?

sckott commented 7 years ago

the onboarding blog posts are about software itself, yes? not uses of that software?

sckott commented 7 years ago

the onboarding blog posts are about software itself, yes? not uses of that software?

stefaniebutland commented 7 years ago

To me, onboarding posts sound like they talk about the software itself plus example uses of the software, with code and example outputs.

But this gets back to how do you / we / rOpenSci define "use cases". Are they supposed to be really short and to the point about a single use of the software? Trying to assimilate how all of these things relate to each other, where the overlap is, and where they are distinct so that we can clearly communicate to our audiences through our site

maelle commented 6 years ago

Is this a place we could list citations of our packages e.g. those that @sckott collects for rOpenSci News e.g. https://ropensci.github.io/biweekly/update-2017-10-09/? Sets a great example showing people it's cool to cite software.

I think the use cases blurbs exist as @sckott's text in the newsletter and on Twitter. Here are a few ideas/suggestions

image

I suggested quoting instead of answering the tweets, I still think it looks better on Twitter (more visible), but then, it makes it hard to retrieve the nice blurbs and screenshots. Sadly I think that retrieving tweets quoting a tweet from Twitter API depends on the "search" endpoint that's limited in time (at least it was the method last time I tried doing something similar )

sckott commented 6 years ago

Have a link to the raw data of all citations? Later it could be a searchable table by package/topic? (and could be fed to the packages docs as well)

Agree to link to citation data.

Would there be a way to digest the newsletter previous issues for that, just to have a direct link that'd be the blurbs from the newsletter? I guess it's also fine to have a link to previous issues in general to start with, not the use cases section. cf #187

Agree to link to newsletter. Not sure the best way to use newsletter use case things on a new use cases page on our site. we probably don't want to overwhelm a user on the page. Maybe they could be grouped by package, and then only shown when you select a package or so?

There could also be a link to the new Twitter account.

Agree

Not sure how to link the tweets Scott's has been writing as reactions to the bot's tweets e.g.

Hmm, I don't think I will keep doing those tweets for every one :)

maelle commented 6 years ago

Maybe they could be grouped by package, and then only shown when you select a package or so?

We might need more structured metadata about packages then, keeping track of where they've been blogged about + in which papers they've been used.

But as a summary easier things mentioned in this thread are adding a link to the Twitter account, to the raw citation data and to the newsletter to the use cases page.

Maybe there could also be a blurb indicating how use cases are currently found, and how to report them (like https://ropensci.github.io/dev_guide/contributingguide.html#reporting-use-cases )

sckott commented 6 years ago

well, we can include how to report, but i think i've maybe had 1 or 2 instances where someone's reported a use case, it's almost entirely our job to do so i think :/

maelle commented 6 years ago

Relevant to this and #10 https://www.divio.com/blog/documentation/

maelle commented 4 years ago

Proposed workflow (not to be implemented now, just writing it here for not forgetting about it).

Semi-automatically convert use cases from the forum + maybe a few from the old html use cases #299 to some sort of Markdown/YAML format under content/usecases (with author, package, title, link, code, image etc. as fields -- leaf bundles to make images easier to store).