Page Comparison

existing developer onboarding resources, across any technologies, to this spreadsheet: https://docs.google.com/spreadsheets/d/1b6DDiikSwo_kOUbU_3htLVc_gsp3PPFvzMzu2QIdUJk/edit?usp=sharing

• Look at next steps for the spreadsheet

• hoping we can develop workshops out of the materials, and pitch how to bridge that gap

• Repo camp offering every year kept those materials up to date

• Documentation has improved because of dev congresses, especially readme

• Do we have a start here? That might be a good goal! Where would we want to send people and start sending people there

• GitHub as the home base for dev focused information. Optimizing for an audience of developers who are going to be working on Samvera adoption.

• Can we start with what are the parts of the repository?

• If I’m a new developer, how do I understand what the problems are that I’m trying to solve?

• Big picture dev onboarding and technologist onboarding, for the person who is stuck figuring out how to make the solution fit their needs

• Someone who might be deploying a Rails app for the first time

• Information architecture: what is the question they are trying to answer when they go to a web page:

  • Repository things that are needed

  • Here is how Hyrax checks those boxes

  • What Hyrax DOESN’T do

• Where do we want people to start? Prioritize can come after focusing on who we ware trying to serve here and what is their problem?

  • Repository manager and I have a Hyrax or I am considering having a Hyrax

  • Developer or devops person who is responsible for deployment

• Entry points for both people: the Readme and the GitHub wiki should be valid for both personas

• Start on Samvera.org getting started page

  • not as bad as we expected!

• the README and the wiki are still valid starting places as well – these three places should point to each other

• Another important place is the ruby doc dot info page for Hyrax. A more advanced set of use cases, but it should point to the other documentation. it is also a thing that needs maintenance. There are some clear errors that are likely not hard to fix in the Ruby docs

• There are so many places where things are and no one is in agreement about where the best documentation

• the documentation for components is in hand for the components

• Need to weed and archive outdated information that is not in the right place

• Whats the relationship between github.io site and other sites? Idea was to centralize documentation as recommended by read the docs dot org, that was the goal. In practice it became subject to the same issues as our code, not getting PRs approved. It could be this site or per project wikis but not both

• there is metadata documentation and workflow that isn’t replicated anywhere else

• it is like a tutorial that takes you through steps, like another genre of information.

• We have great things that exist but most people don’t find it. Might be less confusing

• Confluence as a place for an index of sorts to documentation by technology, pointing to github

Building a contribution guide – Resources Heather found from Open Source 101 talks:

1. Docs or it didn’t happen (the WordPress documentation case study)  – Milana Cap, XWP

2. Open Source Is Not Just About Code: Effective Strategies for Collaboration – Ben Greenberg, New Relic

Tips for creating a contribution guide:

• Make it clear what do you want people to know, do, and why they should care.

• quality readme to answer these questions quickly. Reduces ambiguous language. New Relic Phoenix demo application for an example.

• don't assume knowledge, tell people what you expect of them, transparency in the process of committing a pull request including time it takes

• good first issues, badges, labels, name people for help

• concise readme with badges, transparent contributing guide, link to CoC and anti-harassment, organize with labels, create a plan that is flexible and adaptable
  

Next steps for documentation review/update

Next steps for pattern and practice guidence

Other items