Expand starter tasks #569

cg505 · 2020-01-16T22:16:04Z

These changes expand the starter tasks and also update info on the Slack page. Recommended to review commit by commit.

encadyma

Looks good to me! I think the added details are great.

Long term consideration, but I wonder if it's worth it to also add another section for staff utilities where readers could simulate a "staff hours" scenario where they help out a fake group/user with requests.

cg505 · 2020-01-16T23:49:59Z

Yeah, that's definitely a good idea. Maybe make an issue for it?

dkess

Thanks for working on this! It's nice to see the starter tasks page getting some love, and it's always good to add more tasks.

I feel like some of these changes missed the spirit of the starter tasks page, which was meant to give minimal direction and instead encourage self-teaching. Not only does this fit better with the OCF ethos, but it saves us from having to speculate on the skill level of our audience, which is going to vary widely anyways.

I didn't comment on changes to the Slack docs. I don't have a huge issue with the changes made there, but I think we should merge all the chat docs into one page, that way the Slack docs don't have more information than the IRC docs.

dkess · 2020-01-17T04:54:11Z

ocfweb/docs/docs/staff/startertasks.md

+- `less`: read long files
+- `mv` (move): move or rename files
+- `cp` (copy): copy files
+- `rm` (remove): delete files or directories


This kind of information is out of scope of the starter tasks page. The page is not meant to be a reference, and including this might give the impression that the "solutions" to the tasks can be found based on information on the page. The end goal is for people to figure this out by completing the tasks, not by reading a list of definitions.

This is true, but I wasn't where to guide people as far as learning basic commands. It's not reasonable to just say "log in and learn some commands!" without further guidance, but if there's a good resource to link to or something I agree that it would be better than this list.

dkess · 2020-01-17T04:55:19Z

ocfweb/docs/docs/staff/startertasks.md

+
+Go to our [[command reference|doc services/shell/commands]] page and try running some commands. If
+you want to get more comfortable, try completing [lab
+1](https://decal.ocf.berkeley.edu/labs/b1) from the OCF/XCF Linux System


I'd suggest linking to the archives here, since these links have the potential to break if we ever reset the website for a new semester.

I'll move the current stuff to the archives and link there before merging.

ocfweb/docs/docs/staff/startertasks.md

dkess · 2020-01-17T05:02:54Z

ocfweb/docs/docs/staff/startertasks.md

-community. For example, before creating an account for a student organization,
-we make sure the person requesting the account is listed as a signatory for
-that group. Staff members use the `signat` command to perform this check.
+OCF staff use [[a collection of scripts|doc staff/scripts]] when interacting


This link isn't particularly helpful, since it's a mostly empty page. A link to the signat docs would be more useful. The link gets included later on but I think it's fine to link it in the intro paragraph as well.

I'll remove this link and link the signat mention later in the paragraph.

ocfweb/docs/docs/staff/startertasks.md

dkess · 2020-01-17T05:14:43Z

ocfweb/docs/docs/staff/startertasks.md

+[ocflib]: https://github.com/ocf/ocflib
+[sourcegraph]: https://sourcegraph.ocf.berkeley.edu
+
+## Make a pull request!\*


I like this idea for an exercise, but it's way too hand-holdy. As I mentioned before, the point of this page is for people to learn this stuff on their own and at their own pace. It's fine to give minimal direction here-- maybe mention that you'll need a GitHub account, you'll have to fork the repo and make a pull request, and you should test your changes before submitting a PR-- but other than that the reader should be able to find out how to do this their own. There are plenty of guides for this workflow on the internet.

We do have OCF-isms that you can't find on the internet, like needing to install pre-commit hooks and running make dev to test on supernova.. But this information is in the ocfweb README (which we could provide as a hint). If people forget it, we can remind them in the PR comments.

Part of my concern is that making a PR from a fork is a complicated process, and to be honest there are not good guides on how to do it. I don't think it's really reasonable to expect that people need to have a full understanding of git that includes handling multiple remotes and branches in order to make a contribution. That's the primary reason this guide is so detailed. I would like to strike a better balance but I'm not really sure how to do that.

git kind of just sucks for new people and I'm not sure how to reduce that pain. If you google "how to make a pull request" you'll get a series of results that are somehow worse than this. (Either more hand-holdy while being less descriptive or assuming a lot of knowledge of git already.)

Anyway, I'll try to take another pass at this and make it a bit more self-directed. I can probably remove nearly all the commands and just say "do this" with a link to GitHub docs.

It is safer to err on the side of being prescriptive about the steps, especially basic ones. Git is a major hurdle for most new contributors and is just one of the tools that is part of the 'OCF contribution workflow'. They shouldn't be spending too much time getting set up (causing them to drop out).

cg505

I feel like some of these changes missed the spirit of the starter tasks page, which was meant to give minimal direction and instead encourage self-teaching.

I understand that this was the intention, so the changes I made were more focused on trying to provide pointers that newbies can learn from. "Minimal direction" is only helpful when there are clear paths to more direction/information (besides "ask"), which is what this tries to lay out.

it saves us from having to speculate on the skill level of our audience, which is going to vary widely anyways.

I'm not sure what this means. It would seem to me that we're both speculating, you're just speculating that they have a higher skill level than I am. I intended for the changes to extend the bottom end of applicable skill levels without dumbing things down for those that already were already able to complete everything. I may have missed the mark on the PR task and will look over that again.

I think we should merge all the chat docs into one page

Agreed, but it didn't feel in-scope for this PR.

cg505 · 2020-01-19T01:41:45Z

ocfweb/docs/docs/staff/startertasks.md

+
+Go to our [[command reference|doc services/shell/commands]] page and try running some commands. If
+you want to get more comfortable, try completing [lab
+1](https://decal.ocf.berkeley.edu/labs/b1) from the OCF/XCF Linux System


I'll move the current stuff to the archives and link there before merging.

ocfweb/docs/docs/staff/startertasks.md

cg505 · 2020-01-19T01:43:39Z

ocfweb/docs/docs/staff/startertasks.md

+- `less`: read long files
+- `mv` (move): move or rename files
+- `cp` (copy): copy files
+- `rm` (remove): delete files or directories


This is true, but I wasn't where to guide people as far as learning basic commands. It's not reasonable to just say "log in and learn some commands!" without further guidance, but if there's a good resource to link to or something I agree that it would be better than this list.

cg505 · 2020-01-19T01:44:23Z

ocfweb/docs/docs/staff/startertasks.md

-community. For example, before creating an account for a student organization,
-we make sure the person requesting the account is listed as a signatory for
-that group. Staff members use the `signat` command to perform this check.
+OCF staff use [[a collection of scripts|doc staff/scripts]] when interacting


I'll remove this link and link the signat mention later in the paragraph.

cg505 · 2020-01-19T01:54:12Z

ocfweb/docs/docs/staff/startertasks.md

+[ocflib]: https://github.com/ocf/ocflib
+[sourcegraph]: https://sourcegraph.ocf.berkeley.edu
+
+## Make a pull request!\*


Part of my concern is that making a PR from a fork is a complicated process, and to be honest there are not good guides on how to do it. I don't think it's really reasonable to expect that people need to have a full understanding of git that includes handling multiple remotes and branches in order to make a contribution. That's the primary reason this guide is so detailed. I would like to strike a better balance but I'm not really sure how to do that.

git kind of just sucks for new people and I'm not sure how to reduce that pain. If you google "how to make a pull request" you'll get a series of results that are somehow worse than this. (Either more hand-holdy while being less descriptive or assuming a lot of knowledge of git already.)

Anyway, I'll try to take another pass at this and make it a bit more self-directed. I can probably remove nearly all the commands and just say "do this" with a link to GitHub docs.

ja5087

In general looks good to me. Apologies for not getting to this sooner.

ocfweb/docs/docs/staff/startertasks.md

ja5087 · 2020-01-28T01:22:30Z

ocfweb/docs/docs/staff/startertasks.md

+[ocflib]: https://github.com/ocf/ocflib
+[sourcegraph]: https://sourcegraph.ocf.berkeley.edu
+
+## Make a pull request!\*


It is safer to err on the side of being prescriptive about the steps, especially basic ones. Git is a major hurdle for most new contributors and is just one of the tools that is part of the 'OCF contribution workflow'. They shouldn't be spending too much time getting set up (causing them to drop out).

fydai · 2020-01-28T07:02:00Z

ocfweb/docs/docs/staff/startertasks.md

@@ -6,8 +6,8 @@ free to ask for help in our [Slack workspace](https://ocf.io/slack) or in person
 during [staff hours](https://ocf.io/staffhours)!

 Tasks marked with an asterisk (\*) require staff privileges. If you want to work
-on these but aren't on staff, let a current staffer know you’re working on
- starter tasks and we will add you.
+on these but aren't officially on staff yet, let a current staffer know you’re


I think this should be clarified, "on staff" here means "in the ocfstaff LDAP group"

addressed

This addresses some common issues that should be better documented, and updates the channel lists. We also make some changes to avoid links that just say "here", which can be problems for accessibility.

This adds additional hints and links to the Start Tasks so that new staffers are more likely to progress through them without getting confused and giving up.

The existing Starter Tasks mostly presume knowledge of the command line, which might be overwhelming for someone who hasn't used the command line much or at all, and doesn't know where to find help. This aims to ease people into that more gently by giving them the basics. I expect that many people will already be a little familiar with the command line. These people can simply skip over this task.

Making pull requests is a critical part of contributing the OCF. This starter task will walk people though the process in a lot of detail so that they can start to get comfortable. It also makes an observable change to the actual website, so that the task feels less like a meaningless exercise.

This instruction assumes that the user has SSH keys set up, and is not cloning from a fork. It is also incorrect without a `cd ocfweb` afterwards. In any case "Clone the repo" in the previous sentence should be sufficient.

cg505 force-pushed the starter-task-updates branch from d4d6b22 to 7e01d90 Compare January 16, 2020 23:25

cg505 changed the title ~~Starter task updates~~ Expand starter tasks Jan 16, 2020

cg505 marked this pull request as ready for review January 16, 2020 23:27

cg505 requested review from dkess, BernardZhao, Diplosaurus, encadyma, ja5087 and pxhanus January 16, 2020 23:27

encadyma approved these changes Jan 16, 2020

View reviewed changes

dkess previously requested changes Jan 17, 2020

View reviewed changes

cg505 commented Jan 19, 2020

View reviewed changes

cg505 force-pushed the starter-task-updates branch 2 times, most recently from 1497ffe to fd4e460 Compare January 28, 2020 00:52

cg505 requested review from encadyma and dkess January 28, 2020 00:52

ja5087 approved these changes Jan 28, 2020

View reviewed changes

cg505 force-pushed the starter-task-updates branch from fd4e460 to 40c71b4 Compare January 28, 2020 01:49

fydai reviewed Jan 28, 2020

View reviewed changes

cg505 force-pushed the starter-task-updates branch from 40c71b4 to eb8a312 Compare February 3, 2020 00:01

cg505 added 5 commits February 2, 2020 16:03

update Slack documentation

d61a3ba

This addresses some common issues that should be better documented, and updates the channel lists. We also make some changes to avoid links that just say "here", which can be problems for accessibility.

update Starter Tasks to be more helpful

c4357e3

This adds additional hints and links to the Start Tasks so that new staffers are more likely to progress through them without getting confused and giving up.

remove git clone instruction from README

4d56fd5

This instruction assumes that the user has SSH keys set up, and is not cloning from a fork. It is also incorrect without a `cd ocfweb` afterwards. In any case "Clone the repo" in the previous sentence should be sufficient.

cg505 force-pushed the starter-task-updates branch from eb8a312 to 4d56fd5 Compare February 3, 2020 00:04

cg505 merged commit 7b710c5 into master Feb 3, 2020

jvperrin deleted the starter-task-updates branch February 23, 2020 20:44

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Expand starter tasks #569

Expand starter tasks #569

cg505 commented Jan 16, 2020 •

edited

encadyma left a comment

cg505 commented Jan 16, 2020

dkess left a comment

dkess Jan 17, 2020

cg505 Jan 19, 2020

dkess Jan 17, 2020

cg505 Jan 19, 2020

dkess Jan 17, 2020 •

edited

cg505 Jan 19, 2020

dkess Jan 17, 2020

cg505 Jan 19, 2020

ja5087 Jan 28, 2020

cg505 left a comment

cg505 Jan 19, 2020

cg505 Jan 19, 2020

cg505 Jan 19, 2020

cg505 Jan 19, 2020

ja5087 left a comment

ja5087 Jan 28, 2020

fydai Jan 28, 2020

Expand starter tasks #569

Expand starter tasks #569

Conversation

cg505 commented Jan 16, 2020 • edited

encadyma left a comment

Choose a reason for hiding this comment

cg505 commented Jan 16, 2020

dkess left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dkess Jan 17, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cg505 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ja5087 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cg505 commented Jan 16, 2020 •

edited

dkess Jan 17, 2020 •

edited