Skip to content
This repository has been archived by the owner on Sep 24, 2022. It is now read-only.

contrib guide - initial draft #8

Merged
merged 12 commits into from
Oct 25, 2020
Merged

contrib guide - initial draft #8

merged 12 commits into from
Oct 25, 2020

Conversation

Loquacity
Copy link
Member

Initial draft of the contributors' guide.

Partial https://github.com/thegooddocsproject/planning/issues/6

viraji
viraji reviewed Oct 4, 2020
View reviewed changes
Copy link
Contributor

@viraji viraji left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Loquacity - thanks for this header breakdown.
This would be generic content for a Contributor Guide to all projects within the Good Docs Project, yeah?
I should then also add headers specific to the Base Template Contributor Guide, inside this folder, isn't it?

@Loquacity
Copy link
Member Author

@Loquacity - thanks for this header breakdown.
This would be generic content for a Contributor Guide to all projects within the Good Docs Project, yeah?
I should then also add headers specific to the Base Template Contributor Guide, inside this folder, isn't it?

Yeah, this is contributor guide content which applies to the entire project. The base template content needs to go in one of the two other files in this folder. Just create your own fork and branch and start a new PR.

@Loquacity Loquacity marked this pull request as ready for review October 5, 2020 00:45
@Loquacity
Copy link
Member Author

Considerations for reviewers:

  • I used a > to indicate a command that needs to be typed in, and put output in completely separate code blocks. This is not how I would normally do it for experienced Linux readers, but I was considering that many readers of this doc could be entirely new to anything on the CLI, so perhaps it was warranted. Happy to change it, though, if you think it would work better in a different way. (I also think it messes up the syntax highlighting a bit).
  • I've gone with the same language choice as the IA Guide, for the same reasons, which means my linters are having conniptions. I've addressed a lot of them, but many I've left in for stylistic reasons. Happy to change anything, though, if you disagree.
  • The glossary at the end is incomplete, and it really only covers git terms. We probably need to consider what other terms need to be included, and if we expand to project terms, does it really belong in this guide at all. Also, to get a deflist in markdown you need to use HTML, which is a bit messy.
  • I've used master (to refer to the branch) within the text, but referred to "master or main" in the glossary. This is because we specifically use master in our repos at the moment, but people could be familiar with either term, now that gh has changed the default for new repos.

@Loquacity Loquacity mentioned this pull request Oct 8, 2020
Closed
jaredmorgs
jaredmorgs approved these changes Oct 11, 2020
View reviewed changes
Copy link

@jaredmorgs jaredmorgs left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just one observation about Glossary git terms that you might want to consider before finalising the PR.

base-template/contributors-guide.md Outdated Show resolved Hide resolved
@Loquacity
Copy link
Member Author

Pulled language up a level, removed glossary.

@mgan59
Copy link

mgan59 commented Oct 18, 2020 •
edited
Loading

The git you have listed here on first glance looks solid 💯

mgan59
mgan59 reviewed Oct 18, 2020
View reviewed changes
base-template/contributors-guide.md

Note that pull requests in different repositories within the Good Docs Project require different levels of review rigor.
For example, the `incubator` repo has a much lower standard of code quality than the `templates` repo.
For a full explanation of our review standards, see [insert.link.here].
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

see [insert.link.here].

Specific page in mind? Or this a followup?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think there was work being done on review standards in a gdoc, but I'm not sure it has a home on the site yet.

mgan59
mgan59 reviewed Oct 18, 2020
View reviewed changes
base-template/contributors-guide.md
Assertively enhance functional solutions for synergistic opportunities. Proactively expedite cross-media synergy whereas cutting-edge services. Appropriately embrace principle-centered leadership via leveraged infomediaries. Competently negotiate top-line products through 24/365 experiences. Professionally matrix goal-oriented processes and bleeding-edge experiences.
Like most open source projects, there are always tasks to do.
For the list of issues, see [https://github.com/thegooddocsproject/templates/issues](The Good Docs Project template issues).
Look for issues with a `good first issue` tag if you want something small to start on.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💯 like this idea, just not sure we are tagging things appropriately and we should link to the tags.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I checked, there are a few "good first issue" tags in the repo, but I agree that we should probably review our practices around this.

mgan59
mgan59 reviewed Oct 18, 2020
View reviewed changes
Copy link

@mgan59 mgan59 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added some additional thoughts on content

@Loquacity
Copy link
Member Author

I started reading this and doing a PR request and realized this proposes forks. I'm not opposed to forks I love them. I learned them early on at an organization. But have to be honest, after that org I stopped forking because most orgs I went to did not work on forks. I was unfortunately vilified at one org for working out of a fork. So I just wanted to raise my concerns, that though forking is a better way to git, there are orgs that frown on it

I went with forks because if you don't have any rights in an org, it's the only way to create a PR. So if you're coming to TGDP for the first time, it's unlikely you'll have the perms to be able to do a branch straight up. Also, it's the least destructive way for a novice to interact with git, to my way of thinking, even if branches are easier to manage.

@mgan59
Copy link

mgan59 commented Oct 19, 2020

@Loquacity yeah I realized post writing the comments that forking is the only way to contribute back. Guess it has been awhile since I've worked at organizations where other developers were active in the open-source community. I'm 👍 for this being the correct path for contribution

@Loquacity Loquacity requested review from mgan59 and viraji October 24, 2020 03:12
@Loquacity Loquacity merged commit a93259a into thegooddocsproject:master Oct 25, 2020
@Loquacity Loquacity deleted the contribguide-draft1-lbrindley branch October 25, 2020 04:53
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Reviewers

@jaredmorgs jaredmorgs Awaiting requested review from jaredmorgs

@mgan59 mgan59 Awaiting requested review from mgan59

@viraji viraji Awaiting requested review from viraji

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@Loquacity @mgan59 @jaredmorgs @viraji