Ops Manual Initial Steps

[Rob Spanton]

Hi People,

Over the last few weeks, we've been working towards getting an operations manual
together for SR.  This will define how the whole organisation operates, making
it possible for us to start to get stuff done!

The manual currently partially exists in note form, and we are looking at
completing it over the next couple of weeks.  Please find that note-form version
attached.  We'd love to hear your feedback on its contents.

The notes are currently done in most chapters, except for "Kit Services", "Game
Design", "Kickstart" and "Public Interaction".  Please ignore those chapters for
now -- stuff will come later regarding them.

Cheers,

Rob

[Tyler Ward]

How do you intend that branches fit into the organisational structure as I cant spot anything about them in the attached document.

Tyler

--

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

[Rob Spanton]

Hi Tyler,

On Thu, 2016-02-11 at 14:04 +0000, Tyler Ward wrote:
> How do you intend that branches fit into the organisational structure
> as I cant spot anything about them in the attached document.

Indeed, there is no concept of a "branch" in the ops manual.  However,
there are things that are split by geographical area.  These roles are
generally prefixed with "local", and cover things like regional events
(kickstarts, tech days), as well as mentoring and communication with
schools.

Cheers,

Rob

[Peter Law]

Hi,

Rob wrote:
> Over the last few weeks, we've been working towards getting an operations manual
> together for SR. This will define how the whole organisation operates, making
> it possible for us to start to get stuff done!

Cool, thanks. It's great that you're documenting things which have
thus far only existed in people's heads, with some bits spread out
over trac and the mailing lists.

The levels of detail seem to be all over the place, though I'm
guessing that this is a result of the document being semi-notes,
rather than something intentional. Where the detail is present, it's
generally good.

Some general questions though:
- How are you planning to fit the manual alongside the current
communally-editable
internal documentation, such as the various wiki (trac) pages?

- Is it intended that the document be primarily prescriptive or advisory or some
mix of both (possibly using terms similar to RFC 2119)?

- When are you intending that the things in the manual take effect from?
- Over what duration will it be phased in?
While the majority of it reflects current practices, there are some elements
(such as the mandatory registration of volunteers) which aren't. As someone
organising a Tech Day with non-Blueshirts, it would be a shame if this became
a blocking issue.

Rob wrote:
> The manual currently partially exists in note form, and we are looking at
> completing it over the next couple of weeks. Please find that note-form version
> attached. We'd love to hear your feedback on its contents.

As mentioned, most of what's there is good. Some specific comments follow.

There's quite a bit of mentioning "teachers" and "schools". While the
majority of teams do come from schools, not all do. It would be good
to keep the terminology more neutral where possible, for example using
"team-leaders". (I'm not sure what to use instead of "schools").

> Organising the tech day:
> – Date selection:
> * Must be on a weekend, or alternatively a weekday in a school holiday,
> or bank holiday.

This feels oddly specific and prescriptive -- s/Must/Should/ perhaps?
(I can think of a number of valid scenarios which it currently rules
out).

> *various notes on judge' and linesmen's roles* (ch. 7, s. 3)

These look good, though I wonder if some of them should be in the
rules and/or advertised to the teams at the competition event itself.
They don't quite fir the pit-rules document, but perhaps we should
have some general how-things-will-work notes?

After reading further this seems to be somewhat covered in the notes
about the pits (s. 6, b, ii). Could we expand the four points to
include "How matches operate"?

> The budget is managed in a git repository. The canonical git
> repository for this is hosted at https://bitbucket.org/srobo/budget.
[snip]
> The source code of the operations manual is managed in a git
> repository. The canonical git repository for the manual is hosted
> at https://bitbucket.org/srobo/ops-manual.

Why are these critical repositories planned to be canonically hosted
in a location different to that from all our other repositories, and
to somewhere that may not be accessible to many of the current
volunteers? It currently requires a login, which suggests I wouldn't
be able to access it even if I did have bitbucket credentials.

I understand the desire for the information within the budget repo not
to be fully public, but this is something which we can and have
achieved successfully on our own hosted repos. There seems to be no
reason not to use our own hosting for the operations manual.

> When a claim approval is sent, a copy of the approval must
> also be sent to the treasurers (ideally by CC’ing them in the
> email in which it is sent).

Is there a canonical email address for the treasurers? (I think
treasurers@ exists already) Could we include it in the manual?

> Operations Manual Update Procedure

It would be good to see something in here about notifying and
gathering input from current volunteers (and possibly other interested
parties) before a new version of the procedure is released. I see this
as being particularly important if the intent is for the document to
be prescriptive (rather than advisory, see above query on this).

It would also be good to have something here about how submissions for
proposed changes should work.

Overall I think it's really great that you're moving towards
documenting all the things that SR does and there's a lot of good
content in there.

Thanks,
Peter

RFC 2119: https://www.ietf.org/rfc/rfc2119.txt

[Rob Spanton]

Hi,

On Fri, 2016-02-12 at 22:00 +0000, Peter Law wrote:
> The levels of detail seem to be all over the place, though I'm
> guessing that this is a result of the document being semi-notes,
> rather than something intentional. Where the detail is present, it's
> generally good.

In some places, the ops manual will be detailed, whereas in others it
will be more general.  If there are specific places where more guidance
is required, then we'll have to consider adding more detail.

> Some general questions though:

> - How are you planning to fit the manual alongside the current
>   communally-editable internal documentation, such as the various wiki
>   (trac) pages?

The operations manual, and the things it references, will be the primary
source of information regarding the operations of the organisation.  The
trac wiki is a thing that anyone with a login can edit, and has no
maintenance or approval processes, and so is unsuitable for defining how
the organisation operates.

> - Is it intended that the document be primarily prescriptive or
>   advisory or some mix of both (possibly using terms similar to RFC
>   2119)?

Yes, the RFC2119 thing.

> - When are you intending that the things in the manual take effect
>   from?  - Over what duration will it be phased in?  While the
>   majority of it reflects current practices, there are some elements
>   (such as the mandatory registration of volunteers) which aren't.  As
>   someone organising a Tech Day with non-Blueshirts, it would be a
>   shame if this became a blocking issue.

I wouldn't worry about this too much right now.  We are hoping to have
the first version of the manual done within a few weeks, so this
transition stage can be as short as possible.  Our plan is to have it
sorted very soon so that we can start on the competition etc.

> > Organising the tech day: – Date selection: * Must be on a weekend,
> > or alternatively a weekday in a school holiday, or bank holiday.
> 
> This feels oddly specific and prescriptive -- s/Must/Should/ perhaps?
> (I can think of a number of valid scenarios which it currently rules
> out).

Please can you say what those scenarios are?

> > *various notes on judge' and linesmen's roles* (ch. 7, s. 3)
> 
> These look good, though I wonder if some of them should be in the
> rules and/or advertised to the teams at the competition event itself.
> They don't quite fir the pit-rules document, but perhaps we should
> have some general how-things-will-work notes?

I expect there will be some shuffling within that chapter about where
those bits are.  There are some things that will feature in the ops
manual.

> > The budget is managed in a git repository. The canonical git
> > repository for this is hosted at https://bitbucket.org/srobo/budget.
> > > [snip] The source code of the operations manual is managed in a
> > git repository. The canonical git repository for the manual is
> > hosted at https://bitbucket.org/srobo/ops-manual.

> Why are these critical repositories planned to be canonically hosted
> in a location different to that from all our other repositories, and
> to somewhere that may not be accessible to many of the current
> volunteers?

The 'kit services' chapter doesn't yet have notes in, but it will
contain stuff about vcs I imagine.  I'm expecting that now there are
free hosted services we can use to store both public and private
repositories, that migrating over to using those will be on the cards.
Reducing the NIH syndrome, and etc.

The ops manual git repository is now publicly readable.

> > When a claim approval is sent, a copy of the approval must also be
> > sent to the treasurers (ideally by CC’ing them in the email in which
> > it is sent).
> 
> Is there a canonical email address for the treasurers? (I think
> treasurers@ exists already) Could we include it in the manual?

Yes, there will need to be a section with the contact details of various
parties in it.

> It would also be good to have something here about how submissions for
> proposed changes should work.

Yup, I think we are planning on doing something about this, but all in
good time.  

Cheers,

Rob

[Peter Law]

Hi,

I wrote:
>> - How are you planning to fit the manual alongside the current
>> communally-editable internal documentation, such as the various wiki
>> (trac) pages?

Rob wrote:
> The operations manual, and the things it references, will be the primary
> source of information regarding the operations of the organisation. The
> trac wiki is a thing that anyone with a login can edit, and has no
> maintenance or approval processes, and so is unsuitable for defining how
> the organisation operates.

I realise that the process for submitting changes isn't yet present,
but it already seems to be something which will be (intentionally!)
much harder to improve than the level of detail and prescription it
contains would suggest it should be.

In practise, the low-level details seem quite likely to be the sort of
thing which our volunteers are likely to spot improvements to and want
to have an easy way of adding suggestions to. Even if the trustees
review process merely consists of merging patches, it both seems like
the kind of thing where that would both slow the process down
considerably and largely be a waste of the trustees time. In
particular they could well end up reviewing many small patches
containing details with which they may have little to no actual
experience.

I fear that in turn that the added effort to make these improvements
will either deter contributions (see: the budget, which is now
basically only ever edited by SC members/trustees; srweb, despite
efforts to make it easier to actually edit) or result in other,
competing, guides appearing.

I think we can agree that both of those scenarios are undesirable, so
I would suggest that the ops-manual either restrict itself to a higher
level or enable review (and possibly publishing) from a much wider
number of people.

>> - When are you intending that the things in the manual take effect
>> from? - Over what duration will it be phased in? While the
>> majority of it reflects current practices, there are some elements
>> (such as the mandatory registration of volunteers) which aren't. As
>> someone organising a Tech Day with non-Blueshirts, it would be a
>> shame if this became a blocking issue.
>
> I wouldn't worry about this too much right now. We are hoping to have
> the first version of the manual done within a few weeks, so this
> transition stage can be as short as possible. Our plan is to have it
> sorted very soon so that we can start on the competition etc.

I think that possibly you've missed my point. As someone organising a
Tech Day with non-Blueshirts acting as mentors, I need to know, now,
what the requirements on these people will be in terms of, for
example, their registration with SR and whether the web-form the
manual mentions will be operational within the intended time-scale.

The timing of these Tech Days is publicly available (they're now
advertised on the website), and (one of them) can clearly be seen as
being exactly "a few weeks" from now. In order to not have to cancel
the event at short notice I need to know as soon as possible what the
expectations are going to be.

>> > Organising the tech day: – Date selection: * Must be on a weekend,
>> > or alternatively a weekday in a school holiday, or bank holiday.
>>
>> This feels oddly specific and prescriptive -- s/Must/Should/ perhaps?
>> (I can think of a number of valid scenarios which it currently rules
>> out).

- inset/teacher training days (which aren't holiday as the school is
open, just not to students)
- school activity/extra-curricular days (for example DoE trips
sometimes happen during term time)
- some schools have lessons on weekends (typically Saturday mornings
for those that do)
- not everyone attends formal schooling (we have had teams consisting of such)
- school holidays aren't universally scheduled, whose holiday timings
for should be being used?

Yes, most of these are somewhat pedantic cases which are unlikely to
actually cause issues. However that wasn't really my point.

My point here is that this is a MUST requirement which is then highly
specific and appeared to be considerably more so than the surrounding
content. It also fails to rule out cases where schooling is
interrupted anyway. Simply saying "Ensure the data does not interfere
with normal schooling for teams which could be reasonably expected to
attend" or similar, perhaps using school holidays as an example, would
have the same effect without adding artificial boundaries.

> The 'kit services' chapter doesn't yet have notes in, but it will
> contain stuff about vcs I imagine. I'm expecting that now there are
> free hosted services we can use to store both public and private
> repositories, that migrating over to using those will be on the cards.
> Reducing the NIH syndrome, and etc.

Bitbucket, Github and Gitorious (just the first three I checked) were
all launched/founded in 2008. Given that we started using git
ourselves around 2010 (based on the last commit date in SVN), the
availability (or lack thereof) of free hosting doesn't seem to have
been a driving force in our choice to self-host.

I don't disagree that there may be some benefits to moving, though it
would represent a (possibly substantial) change in everyone's
workflows. Given that it would seem sensible to invite discussion
around the idea of moving, along with platform suggestion, before
doing the move (if indeed that turned out to be preferable).

> The ops manual git repository is now publicly readable.

Thanks. I've no idea how to use bitbucket -- is there a way we can
send pull requests (or some equivalent)?


Thanks,
Peter