Documentation suggestions

[RichardLitt]

👋 Hey there! This is the developer experience audit from @mntnr for this repository. I've added in my thoughts below, in the form of a checklist. Looking forward to seeing what you think; let's see if we can resolve all of the open issues and make this repository shine ✨ 💖 ✨

Repository Review: splitrb/split.js

📉 Clientside A/B testing library

For notes on anything crossed out, look below. Note: I use [~] to mean that I have proposed a fix in a PR. I know it doesn't render properly in Markdown, but it works pretty well otherwise for that purpose. If I think that something is fine, even if it isn't valid according to this checklist, I've checked it off and included a note.

Reviewing the Repository Docs

• Is there a README?
  • Does it follow standard-readme?
  • Is it spellchecked?
• Is there a Code of Conduct, such as the Contributor Covenant?
  • [~] Is it mentioned in the Contribute section of the README? (Note: this isn't needed if you mention it in your CONTRIBUTE.md and it is in this repository.)
  • Does it reference an email address for violations?
  • Does it reference a second email address?
• Is there a LICENSE file?
  • [~] Is this matched in the package.json?
  • [~] Is the year correct?
• Is there a .github or docs folder? This is so low traffic I wouldn't bother.
  • Is there an ISSUE_TEMPLATE.md?
  • Is there a PULL_REQUEST_TEMPLATE.md?
• [~] Is there a CONTRIBUTING.md file?
  • [~] Does it mention how to make a PR?
  • Does it mention what sort of issues you'd like?
  • Does it mention a good first issue label as a starting point?
  • Does it mention triaging and bug reports as good starting points?
  • Does it point to a community chat program, like Slack or Gitter?
  • Does it encourage conversations in issues before opening huge PRs?
  • Does it specify where to ask questions on process?
  • Does it explain labels used in the issues?
• Is there a CHANGELOG?
  • If there isn't, are notes included in the project's releases?
• Does this pass alex adequately? Run alex *.md.
• Does the repository name itself pass on http://wordsafety.com?

Process

• [~] Can I install easily? I am going to say no. I would add this to npm. I've suggested a package.json file
• [~] Can I use this easily? Easier with the package.json.

Issues and Pull Requests

• Are there an acceptable amount of pull requests?
• Are there an acceptable amount of issues?
• Are an acceptable amount of issues less than six months old?
• Are there useful issue labels?
• Are the labels being used? No open issues
• Is there a good for beginners or good first issue label?
• Is there a waiting on contributor label?

Bots

Note: Neither of these are necessary, but they can help with some things. Check out https://probot.github.io/ for some tools.

• Are there bots enabled?
• Are the bots listed in the Contribute or Readme files so that users can expect to interact with them?

Metadata

• Is there a description on GitHub?
  • [~] Does the description match the README?
• Are the topics useful? I would add some: split, splitrb, testing.
• Is there a website?
  • Does the website match the project?

Package Metadata

Note: These should apply to package.json (JavaScript), *.cabal (Haskell), and metadata.yml (Perl), among others.

• [~] Does the description match the GitHub description?
• [~] Is there a bugs field?
• [~] Is there a homepage field?
• [~] Are there appropriate keywords?
  • [~] Do these match the topics on GitHub?
• Run depcheck; do the deps make sense?

TODO

The main thing that this repo needs is a basic package.json. Otherwise, it's pretty solid.

Generic

• Add a link to your Split Google Group! You want to engage with users there.
• Consider adding a secondary email to the Code of Conduct as a contact - someone may have an issue with you but not want to tell you directly. I know, this idea may be awkward. But you will give them an option in case they do have an option, and this may be good for the overall health of the project. I'd be happy to suggest my email for this use case.

Issues

• Considering adding available labels as well as good first issue. These can be used to signal that you're looking for community involvement for issues. They can also be configured to display on http://up-for-grabs.net. This will help more people interact with your code, and lead to small, iterative work done by others. It may take some time to set up initially - properly scoping issues for newcomers takes some time - but the payback should be worth it.

Contribute back?

This checklist is open source! If you have suggestions or think it could be better, contribute back on mntnr/audit-templates.

As well - note that you don't need to tick every box. If you have anything you'd like to talk about, I'm here; otherwise, I would suggest either pulling out tasks into a comment before, or into other issues, and then closing the issue when you feel you've adequately done everything. If you want help here, let me know.

Thank you!