Documentation edits

[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-api

📶 JSON API to the split 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? More or less.
  • Is it spellchecked? See TODO section below for minor issues.
• 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 .gemspec?
  • [~] Is the year correct? Year is 2013 (NB: latest release is 2018).
• Is there a .github or docs folder? See TODO section below for recommendation.
  • Is there an ISSUE_TEMPLATE.md?
  • Is there a PULL_REQUEST_TEMPLATE.md?
• [~] Is there a CONTRIBUTING.md file? See TODO section below for recommendation.
  • [~] 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. 5 warnings, all false positives.
• Does the repository name itself pass on http://wordsafety.com?

Process

• Can I install easily?
• Can I use this easily?

Issues and Pull Requests

• Are there an acceptable amount of pull requests? 0 open, 1 closed at time of audit.
• Are there an acceptable amount of issues? 1 open, 0 closed at time of audit (one open is asking about status of repo).
• Are an acceptable amount of issues less than six months old? 1 open, 0 closed at time of audit.
• Are there useful issue labels? Just one label, help wanted.
• Are the labels being used? N/A: no substantive activity.
• 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? N/A.

Metadata

• Is there a description on GitHub?
  • Does the description match the README? See note in the TODO section below about the GH description; if that changes, then this should, too.
• Are the topics useful? No topics; this is noted in the TODO below.
• Is there a website? None listed; this is noted in the TODO below.
  • Does the website match the project? N/A.

Package Metadata

Note: These should apply to the .gemspec file here.

• Does the description match the GitHub description? But see note in the TODO section below about the GH description; if that changes, then this should, too.
• [~] Is there a bugs field?
• Is there a homepage field?
• Are there appropriate keywords?
  • Do these match the topics on GitHub? N/A.
• Run depcheck; do the deps make sense? No package.json file.

TODO

• Given that the "Usage" section of the readme just says "TODO", along with the fact that the repo seems generally unfinished, makes it unclear whether this is a completed, functional project. In fact, someone asked the same in an issue ("status of this repo"), and the info can be found in a comment there, but it would be better, given that this is functional, to update the documentation so that it doesn't look unfinished, or, lacking that, to perhaps add a note to the readme indicating the status of the repo.
• [~] Make changes so that the README conforms to the standard-readme spec; the following criteria aren't met:
  • The short description does not match the GitHub repo description (see notes on Short Description field in standard-readme for suggestions on setting this up).
• [~] Spelling issues I would recommend correcting:
  • Suggest changing the GH description to "Split extension to provide REST-based JSON API", and matching this everywhere it doesn't match (in particular, the readme and .gemspec).
  • If not, then:
    • Change "ab" to "A/B" in the GH description.
    • Change "api" to "API" in the readme's description.
• As this is an extension to split, consider pointing back to split for duplicative elements which you do not want to replicate in its extensions, such as info on how to contribute (including) how to manage issues and PRs). If not, I recommend creating a CONTRIBUTE.md similar to the main split repo's (see list above for recommended elements to include).
• I recommend either creating a CHANGELOG, or including a note in each release briefly stating what the release included.
• I would recommend adding topics to the repo below the GH description.
• If this project has a separate website, I recommend adding it to the repo (specifically, in the GH description).
• If it would be of benefit, add the missing elements listed above in the Package Metadata section to your split-api.gemspec file.

Generic

• I would add a maintainers section, to make it clear who is on the maintainers team. This helps set expectations and clarifies for the users who they can talk to.
• Add a link to your Slack or Gitter! You want to engage with users there. The main split repo points to your Google Groups; this works unless you have a different collaboration medium you prefer (but recommend adding to Contribute section of readme and/or CONTRIBUTE.md).
• 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 add mine if you want a third party one.
• If you plan on this being an active project, consider adding ISSUE_TEMPLATE.md and PULL_REQUEST_TEMPLATE.md files to your repository. These may help you in the future.
• This audit does not cover license dependency. For that, I suggest using either licensee or an external tool like Fossa. Let me know if you want more help here.

Issues

• Consider 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.
• I label pull requests where I am waiting on the Contributor to respond waiting on contributor. This helps alleviate pressure on you to close them.

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!