Update GitHub documentation #447
Conversation
|
@nonprofittechy I made a few updates in order to include information about uploading a package, and that led me to add some further notes on naming packages before publishing to GitHub (addressing #434). Which then made me realize the name formats page was not showing up anywhere in the sidebar, so I fixed that, too. |
There was a problem hiding this comment.
No worries! It was a group effort and a lot of fun. The audience was very different and some external documentation didn't exist, or was insufficient in our opinion, when we first created this, so there is plenty that's redundant. Anyway, documentation gets outdated.
I love the work here, though I miss some of the pictures. It's wonderfully concise and to-the-point. I like leaving the docs up to the people who make the software (where possible, of course). I made some suggestions, but you can take them or leave them. A couple are just plain language tweaks, and I later decided this probably isn't the PR for deep plain language revisions and I'm not the expert anyway. There are some typo fixes too.
I think it's basically ready for prime time. I'll approve and if you want me to read updates just let me know 👍
|
|
||
| One convention for branch names: They're to remind you and your collaborators basically what it's for at a glance, so one to three words separated by underscores is usually a good guideline. Example: income_questions or income_calculations. | ||
| Refer to the [GitHub documentation for how to create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). |
There was a problem hiding this comment.
This section doesn't add information. Instead of having a section here, the docs could just link straight to the github docs:
"Such and such, make a pull request, and..."
There was a problem hiding this comment.
That said, we have stuff in "reviewing a pull request" that the requester should have done, like giving suggestions on what to test and linking issues, that aren't in this section or in the GitHub documentation.
There was a problem hiding this comment.
I agree, but I also think it makes sense to see this in the sidebar:
How To
- Commit Your Code
- Create a Pull Request
- Resolve Conflicts
- Review Pull Requests
And the section on reviewing pull requests is for reviewers, not for creating it in the first place. So I think I'm going to leave it for now, but I will keep it in mind for future updates.
I'm sure the next cohort of interview builders will run into different problems that I can use as prompts for future updates.
Co-authored-by: plocket <52798256+plocket@users.noreply.github.com>
Co-authored-by: plocket <52798256+plocket@users.noreply.github.com>
…thub.com/SuffolkLITLab/docassemble-AssemblyLine-documentation into onboarding_updates_RE_2024_summer_cohort
This is a PR for updates related to the LIT Lab's 2024 summer cohort. In the course of that work it became clear we needed to update the GitHub instructions to help student teams work together. This update primarily addresses that, along with some additional minor changes.
Some notes: