Badges, badges, badges!

[gaborcsardi]

Everybody loves badges, right?

So how about we create some more CRAN and/or R related badges? Here are some ideas.

Badge for CRAN package checks.

From metacran/metacranweb#87

Badges for maintainers

From metacran/metacranweb#88

We could also have a mega-badge for a maintainer, that would include the summary of the check status for all CRAN packages, i.e. the information from https://cran.r-project.org/web/checks/check_results_csardi.gabor_at_gmail.com.html

Some more ideas, loosely defined currently:

• badge for good documentation. I.e. there is a nice readme, all manual pages have examples, etc.
• badge for readable code. I.e. functions are short and simple, functions are pure, they avoid anti-patterns (sapply, attach, ...) etc.

[thibautjombart]

Yes, yes, yes!
:)

[maelle]

There was some badge-related discussion in #41 (mostly available packages, and how they should be placed)

[hadley]

I think we also need a metabadge that lists how many badges your package has 😜

[sfirke]

The loosely-defined badges overlap a little with #49. As a user I'd be instantly more interested in packages with badges for the short and simple functions and good docs (and I'd like to see packages that self-identify as "pipe-friendly" or "tidyverse-aligned"). A badge like "good documentation" could be an inspiration to package developers to meet a certain set of a best practices.

[stefaniebutland]

@sckott @karthik badges for good documentation fits with what we've discussed recently, yes?

[karthik]

Documentation coverage is a bit harder to quantify (or at least that is my naive take), but would be nice to know what % of functions are documented versus @noRd.

[sckott]

Sounds good @stefaniebutland - wonder if goodpractice already has something that can be adapted for doc coverage

[gaborcsardi]

@karthik you mean internal functions? Exported functions have to be documented, otherwise R CMD check freaks out. But yeah, documentation coverage is not as easy to define.

Documenting the internal functions is often nice, but I would not consider it as a requirement. Maybe.

Anyway, there are a bunch of things that we could check automatically:

• there is a README(.md) or other package level documentation
• there is a NEWS(.md) file
• manual pages tend to have examples
  are the ones that seem obvious to me.

[jimhester]

I think the current CRAN badge should maybe be changed to automatically show the CRAN check status. Mainly so package author's know when it is broken on CRAN, since I for one usually don't realize it is broken until I check the page before submitting a new version.

[gaborcsardi]

goodpractice does not really have too much about documentation AFAIR.

[gaborcsardi]

@jimhester that's a good idea, but maybe some direct notification would be more appropriate, no?

[jimhester]

@gaborcsardi, probably true, but CRAN doesn't do that currently.

Back on topic a badge for the number of required package dependencies (Imports and Depends) could be useful.

[karthik]

you mean internal functions?

No!

Exported functions have to be documented, otherwise R CMD check freaks out. But yeah, documentation coverage is not as easy to define.

But it is easy to fudge this and write almost nothing. Try looking for help on functions on the magick package (which I really like, but Jeroen has had that as TODO for someone to help with). So that's what I mean by not sure how to quantify. Do we do a word count of how verbose documentation is for a function (which wont make sense if a function can be easily described in a sentence or two).

[jimhester]

One thing you can do is have a badge for example and vignette coverage, see also #2

[gaborcsardi]

which wont make sense if a function can be easily described in a sentence or two

Exactly. Small/simple functions are great, and they tend to have small manual pages.

[karthik]

Exactly. Small/simple functions are great, and they tend to have small manual pages.

I agree with you. But that reflects a style that we hope more people will adopt but doesn't solve the task at hand.

A use case I'm thinking of is a complex function with lots of input arguments (with defaults). It would be really helpful if the author clearly documented what each argument did, and how it might change the outcome. For many packages I've spent hours trying to understand the intention of a function because there was one ambiguous sentence (but a dozen poorly described inputs).

[thibautjombart]

I like the idea of stats reflecting doc quality!
For the small functions / short doc: how about the ratio of code / doc?
Otherwise another measure of doc coverage could be, for a given function, the number of times it is called directly in examples, README.Rmd (if present), and in vignettes?

[jimhester]

I think often R documentation is criticized for being to verbose actually, so I am not sure more documentation is the answer. Often good usage examples goes farther than more prose.

But I also personally find writing documentation the hardest part about writing a package, so I am probably just biased.

[karthik]

I think often R documentation is criticized for being to verbose actually

I wasn't exactly going for verbose, but just enough text to accurately describe something. One can be verbose and still not help someone trying to use the function.

[thibautjombart]

Yes, the code / doc ratio quality may be bell-shaped. I agree, verbose is not necessarily ideal. Accuracy of the description is going to be harder to quantify though ;)

For examples, the case may be stronger. Well, there'll always be room for bad examples, but a function directly called several times in examples and vignettes may be better documented than one that is barely illustrated in practice?

[karthik]

Can someone point be to bad verbose documentation in R?

[MilesMcBain]

@karthik IMHO: help("regexpr") is verbose and bad. I reckon combining the docs for related functions and ending up with a noisy mess is an R documentation anti-pattern.

Also my favourite example of concise and bad is: help("prop.table")

I'm loving this idea of a "Good Docs" badge. Another way we could go with it would be a curated list like a task view or @daattali's addins list. Badge would be a given based on adherence to some criteria. You could make it an optional thing that gets given out as part of the rOpenSci Onboarding process. Something for authors to strive for.

[gaborcsardi]

How about using tools for readability and inconsiderate writing? E.g. http://wooorm.com/readability/ and http://alexjs.com/

These are implemented in JavaScript, but they can be ported to R easily I think.

[karthik]

@MilesMcBain Sweet, thanks! Both are great examples! damn, the docs for prop.table are bad

I suppose I should clarify that I'm looking for succinct but crystal clear. To me verbose/bad is just as terrible as short/useless. From what I am reading, it seems like good docs badge would be really hard to assign programmatically, or from goodpractice but come from a human review.

[thibautjombart]

@karthik this may deserve its own issue? I'm happy to sum the doc related part of the discussion in a separate issue if useful. Would be nice to nail down a set of good practices for documentation. Not unrelated, I was wondering if we could come up with a standard way of writing cheat-sheets - maybe not as pretty as the ones Rstudio produces, but with similar content, i.e. 1-pager with main package workflows / functionalities.

[batpigandme]

@thibautjombart Though it's not in R itself, I did discover that RStudio has a cheat-sheet-making cheat sheet https://www.rstudio.com/resources/cheatsheets/how-to-contribute-a-cheatsheet/

[thibautjombart]

Niiiice! Though.. I'm a hopeless emacs user :-/

[jsta]

@thibautjombart I made an attempt to reproduce the RStudio cheat-sheet style with beamer: https://github.com/jsta/imagemagick_cheatsheet

Nowadays I would probably try to adapt https://github.com/odeleongt/flexdashboard-poster

[thibautjombart]

I moved this cheat-sheet conversation to a separate issue: #73

[fmichonneau]

One badge that I would find useful is: "xx commits since the last CRAN release" to give you an idea on how divergent the dev and release versions are.

[batpigandme]

I'm really interested this despite the fact that (true confessions) I honestly don't have a great handle on what all the badges that are currently in GH repos actually mean, per se... Any useful recs for reading a bit of a crash course, and/or sense if this is just callow me, or if others are in the same oat?

[jimhester]

@batpigandme Usually the badges are links that can be followed to get more information, or they have text when hovered that explains. Did you have one in particular you did not understand?

[batpigandme]

@jimhester Oh, cool! Thanks, I'll do that, then. I can be click-shy when it comes to things I don't know about, not wanting to somehow blow everything up.

[karthik]

@batpigandme They are small SVG files that are created on the fly. You can make up any badge you like here. So badges are just images in a markdown file in this case, with information like CI status, version, downloads etc being added on the fly.