diff --git a/docs/environment/culture.md b/docs/environment/culture.md new file mode 100644 index 0000000000000000000000000000000000000000..7747970ccf945b7f165821968510fde6547752b3 --- /dev/null +++ b/docs/environment/culture.md @@ -0,0 +1,75 @@ +title: Culture and Values + +# Shared culture and values + +We, as a division, regularly meet to try and reflect on what things about our +culture, values and ways of working are good and which need improvement. These +meetings can be as a group or as one-to-one sessions with line managers. This +page documents some specific observations from these retrospective sessions. + +## Good documentation is paramount + +The moment you stop working on something, details of its operation start leaking +out of your head. Documenting processes and procedures helps guard against this. +On multiple occasions we have had difficulties arising from the loss of a +single-point of failure or simply that something had been forgotten over time. + +We discussed and developed some strategies for good documentation: + +1. Write the documentation you would want for yourself in six months. It is hard + sometimes to know who the audience of documentation is. Unless there's a + clear audience, write assuming that it is you who'll be re-visiting this + topic in six months and write the documentation you'd want to find. +2. Merge requests can and should be moved back to rework if they do not include + documentation. This documentation should include good commit messages. In + six months time you may be staring at a line of code wishing that you'd + written down your thought process in a commit message at the time. +3. When extended design work is being performed prior to implementation work, it + is useful if that design work can be captured and discussed at the earliest + opportunity. Team members should feel empowered to ask someone performing + high-level design to keep notes and to be willing to talk through the design + as they are working on it. + +## Keep working state in GitLab + +We are increasingly finding ourselves needing to be more work-from-home and +asynchronous-friendly. To that end it is everyone's responsibility to keep state +in a shared place. This place is usually GitLab. + +1. Make sure that GitLab issues contain enough information for someone to start + work on it. Single-line issues should be extremely rare. The issue + description or the comments below should reflect the discussion which + happened in sprint refinement. +2. GitLab issues should be short-lived once picked up. If an issue unpicks to + have a number of sub-issues which weren't anticipated initially, split the + issue into sub-issues, close the parent issue and start work on the first + sub-issue. + + Sub-issues should be grouped together using GitLab's "related issue" + mechanism. + +## It is OK not to know something + +We are a cross-product team with many difference specialisms. Do not be afraid +in a sprint refinement session to ask for clarification on an issue if you do +not understand the problem it is describing. + +Attempt to make time to explain concepts to other team members when asked. +Explaining things is a useful transferable skill and one which we all can +benefit from developing. + +If you feel that something is being designed or developed without enough context +being recorded, feel free to open an issue and request that it be scheduled. + +## It is OK to claim an issue if you are less knowledgeable on it + +Our issue estimation process attempts to capture differing familiarity within +the team about specific technologies. If an issue deals with a technology +unfamiliar to you it is OK to pick it up regardless and ask for help. Please try +to document your learning when tackling the issue as "from nothing" +documentation is very hard to write. + +If you pick up an issue on a topic you are less familiar with, it is your +responsibility to identify quickly if you have a knowledge issue which is +blocking process and to ask someone for help. If no one can help you, place the +issue back into the backlog and choose another. diff --git a/mkdocs.yml b/mkdocs.yml index 5a0d3050eb9f719854c08d7172e7e1f1e3965609..2cf9f5c6ff10f9fee0b5c8ce1115e7e52672e387 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -51,6 +51,7 @@ nav: - services/tls-certificates.md - services/undergraduate-admissions-portal.md - 'Working environment': + - environment/culture.md - environment/meeting-rooms.md # Links for sufficiently with it people to submit changes.