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-export

📂 Split extension to export your data

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? See TODO section below for non-conforming criteria.
  • 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? Year is 2013 (NB: latest releases are 2016).
• 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, 2 closed at time of audit.
• Are there an acceptable amount of issues? 1 open, 12 closed at time of audit.
• Are an acceptable amount of issues less than six months old? 1 open, 2 closed at time of audit.
• Are there useful issue labels?
• Are the labels being used?
• 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?
  • Does the website match the project?
  • Mostly. The documentation pulls directly from the GitHub README, but the installation is a little different (the website indicates to pass a version flag, which the GH readme does not).

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? 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.

TODO

• [~] 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).
• 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 suggest changing the GH description to "Split extension to export your A/B testing data", and matching this everywhere it doesn't match (in particular, the readme and .gemspec).
• 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.

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 https to your repository website link. Currently it is http.
• 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.
• Consider adding ISSUE_TEMPLATE.md and PULL_REQUEST_TEMPLATE.md files to your repository. It looks like you have your PRs well under control, but these may help you in the future. At the least, ask contributors to read the Usage guide.
• 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!