Volunteer Handbook Update

[Tom Leese]

Hi all,

At the last activity day a few of us started work on the volunteer
handbook and I've been doing some more work on it today.

For those who aren't aware, the volunteer handbook is meant to be a
single page on the website that volunteers can access on their phone, or
print out, or whatever, for when they're mentoring or doing other
Student Robotics business. The handbook provides useful information to
volunteers new and old, but it is meant to be a good starting point and
piece of marketing for new volunteers in particular.

This email is really just meant as a progress update and a chance to get
a preview at what the final product will look like. The latest
development version will always be available at
http://srobo-playground.github.io/volunteer-handbook/ so you can take a
look at how it progresses over time.

If anyone else is interested in helping, please get in contact with me
(perhaps off-list to avoid unnecessary spam).

Tom

[Peter Law]

Hi,

Tom wrote:
> At the last activity day a few of us started work on the volunteer handbook
> and I've been doing some more work on it today.

Very shiny, looking forward to seeing the completed version.

> The latest development version will always be available at
> http://srobo-playground.github.io/volunteer-handbook/ so you can take a look
> at how it progresses over time.

What's the longer-term plan for hosting this? http://srobo.org/volunteer ?

Thanks,
Peter

[Tom Leese]

Hi Peter,

On 22/02/15 21:21, Peter Law wrote:
> What's the longer-term plan for hosting this? http://srobo.org/volunteer ?

Yeah, it'll be hosted in a similar manner to the community guidelines,
with appropriate links to it on the main website.

Tom

[Tom Leese]

Hi,

Work has been slowly working on this in the past few months and it's now pretty much complete except for the incident chart at the bottom which needs some thought. I would appreciate anyone taking a look over it and letting me know what they think.

http://srobo-playground.github.io/volunteer-handbook/

Tom

[Peter Law]

Hi,

> *sub goals*
> For example, start with a robot which moves in a straight line,
> then one that turns towards markers and then one that drives
> towards markers, etc.

I think it may be worth emphasising somewhere (and thus possibly
picking slightly different examples here) that moving in a straight
line is actually quite hard, even for teams with a couple of years'
experience.
With that in mind, perhaps the sub goals could be:
- having the kit move the motors in a controlled manner
- having a chassis which moves
- completing the rookie challenge
- having a robot which moves towards markers

I'm not sure how much this is intended to be directly guidance and how
much is high level general ideas, so we may want more or fewer
examples & details, but I do think we should pick examples which we
know actually fit (as well as look like they fit from the perspective
of a new person).

Peter

[Peter Law]

Hi,

Apologies for the abrupt critique in the last email. Overall it's
looking fairly good now. What's the best approach for raising issues?

Separately, another issue follows:

> *debugging*

> You can get your team to build a minimal set up with only
> the required boards and peripherals plugged in .....

This sentence starts rather out of nowhere, and needs something to
lead into it. Perhaps it could be worded:
> If the team experience problems with their robot you can get
> them to build a minimal set up with only ....

Peter

[Samson Danziger]

Hi,

I have a few comments.

I think the links to Trac and the tools page should be much more obvious, I'm not sure how this would be done, but I missed both of these links the first time round, and almost completely missed the Trac link. Similarly, I think trac and gerrit should be in the glossary.

Something which I think needs to have some thought, although I'm not sure it should go in the handbook, is account creation. You can't do any code review, or make any commits (I believe), add to trac or use the forums or ide without an account. Maybe in the handbook, there could be a note that says that you need an account for these things, and how to get one. Unless the handbook is for people who already have accounts, in which case is there a way that this occurs?

Other than that, all looks good to me.

Samson

--
You received this message because you are subscribed to the Google Groups "Student Robotics Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to srobo-devel...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Peter Law]

Hi,

A couple of other more general things:
- "Keeping up to date" introduces the idea of mailing
lists, but doesn't link to them
- "Where does it go from here?" mentions branches,
but doesn't explain them (and they're not mentioned
anywhere else; something for the glossary?)

> *where does it go from here*
> If you’re familiar with the command line

This phrase reads oddly to me. Perhaps "If you're familiar with
working from a command line" or similar?

Peter

[Peter Law]

Samson wrote:
> Something which I think needs to have some thought, although I'm not sure it
> should go in the handbook, is account creation. You can't do any code
> review, or make any commits (I believe), add to trac or use the forums or
> ide without an account. Maybe in the handbook, there could be a note that
> says that you need an account for these things, and how to get one. Unless
> the handbook is for people who already have accounts, in which case is there
> a way that this occurs?

The current process for getting an account is that people email
accounts@SR with some details about who they are. I believe this email
goes to Jeremy for the moment. I'm guessing that the process also
involves some reality checking with people on the ground near the new
volunteer before the account is actually created.

Unfortunately I don't know where that fits with the handbook though.

Peter

[Tom Leese]

Hi Peter,

> On 29 Jun 2015, at 21:25, Peter Law <peter...@gmail.com> wrote:
>
> Hi,
>

> What's the best approach for raising issues?

I think it’s at a point where we can put the handbook into a Student Robotics Git repository, which I will aim to do today. After that, I think the best way would be to raise a ticket on Trac, although I’m not sure what the best component would be, or perhaps a ‘volunteer-handbook’ tag should be used.

Tom

[Peter Law]

>> What's the best approach for raising issues?

Tom wrote:
> I think the best way would be to raise a ticket on Trac,
> although I’m not sure what the best component would be,
> or perhaps a ‘volunteer-handbook’ tag should be used.

There is an existing 'Internal Docs' component which could be used,
though a separate component would also be reasonable.

Peter

[Tom Leese]

Hi,

On Wednesday, 1 July 2015 07:39:16 UTC+1, Tom Leese wrote:

I think it’s at a point where we can put the handbook into a Student Robotics Git repository, which I will aim to do today.

This has happened, it is in a 'volunteer-handbook' Git repository and will have similar restrictions to srweb, requiring three +1s and one verify for patches to go through. 

Tom

[Harry Cutts]

Hi Tom,

On Monday, 29 June 2015 20:15:02 UTC+1, Tom Leese wrote:

Work has been slowly working on this in the past few months and it's now pretty much complete except for the incident chart at the bottom which needs some thought. I would appreciate anyone taking a look over it and letting me know what they think.

I've submitted a spelling and grammar fix patch [0], but other than that, looks good! Thanks for working on this.

Harry Cutts

[0] https://www.studentrobotics.org/gerrit/2448

[Jeremy Morse]

Hi,

On 29/06/15 20:15, Tom Leese wrote:
> Work has been slowly working on this in the past few months and it's now
> pretty much complete except for the incident chart at the bottom which
> needs some thought. I would appreciate anyone taking a look over it and
> letting me know what they think.

This is looking really good, thanks for putting it together. I have a
couple of opinions to vend, mostly related to what that aim/purpose of
mentoring is. There's no real truth behind these opinions, only what my
experience is.

IMO, I'd say mentoring is about encouraging the competitors to follow
engineering processes, and the handbook covers that (prototype things,
reduce to smaller problems, etc). I'd suggest this should be extended by
encouraging competitors to try things out, even if they're going to
fail: finding out what doesn't work and being able to understand why is
an extremely important skill for people to learn. Not being fearful of
things breaking is an extremely important way of breaking analysis
paralysis.

(Obviously, there are limits: if purchasing £100 of obviously incorrect
motors, or setting fire to our equipment, the cost of experimentation
outweighs the subsequent enlightenment).

On a more organizational front, I'd say mentoring is an extremely
important part of fixing the mentality of competitors. If someone
external is visiting weekly / frequently, this makes Student Robotics
much "real-er" than if we're only connected to them electronically.
There's (IMO) a psychological pressure to deliver progress in return for
someone helping, and giving competitors that motivation to make things
happen is another facet of learning to do things.

~

Two tidbits: one team this year told me they'd spent months writing
their code in the simulator to make their robot move forwards, prod a
token, and move back; but that at the competition their code didn't make
their real-world robot do the same things! While it might be obvious,
IMO the simulator needs a health warning that it's a prototyping tool.
(Volunteer handbook might not be the best place to put it, but I don't
know where else to say this),

For the debugging process (which is good), IMO an additional step is
that the competitors need to clearly state what the expected behaviour
is (so that they can then compare it with what actually happens).

~

[Javascript on my lawn, gripe gripe, etc.]

--
Thanks,
Jeremy

[Harry Cutts]

Hi,

On 11 July 2015 at 15:23, Jeremy Morse <jeremy...@gmail.com> wrote:

Two tidbits: one team this year told me they'd spent months writing
their code in the simulator to make their robot move forwards, prod a
token, and move back; but that at the competition their code didn't make
their real-world robot do the same things! While it might be obvious,
IMO the simulator needs a health warning that it's a prototyping tool.
(Volunteer handbook might not be the best place to put it, but I don't
know where else to say this),

I've submitted a Gerrit patch [0] which adds this to the simulator's docs page.

Harry Cutts

[0] https://www.studentrobotics.org/gerrit/2452