Handbook

Getting started

Kyan HQ & Hybrid Working

Structure

Slack

Kit, equipment & new shiny 

Our culture

Holidays

Benefits

Harvest and recording time

Training & development

Volunteering

Practical stuff 

Fire evacuation plan

Family Leave

Expenses

Insurance

How to give feedback

Credit card spending

Policies

Family leave

Breastfeeding at work

Code of conduct

Information security policy

Cycle to Work

Disciplinary policy

Environmental policy

Ethical marketing policy

Equality policy

Flexible working policy

AI usage policy

Health & safety

Ergonomic safety at work

Volunteering Policy

Employee data policy

Data protection policy

Whistleblower policy

Sickness

Mental health policy

Time off For public duties

Social media policy

Time off for dependants policy

Hazardous waste in the office

Client Ethical Policy

Anti-harassment and bullying policy

Working from home (WFH) 

Internship policy

Anti-corruption & bribery policy

Holiday policy

Performance Improvement Plan Policy

Environmental purchasing policy

Engineering

Engineering philosophy

Technology Selection / Stack

Version control

Code review

Automated testing

JS Testing

Continuous integration

Quality assurance

Culture

DevOps

Engineering people

Security

Learning & development

Front End

Approach

Toolbox

Learning and Development

Design

Our Design Principles

Toolset

Branding & Identity

Product Design

Design System

Processes

Intro

Probation period

Guidelines

Writing Content

* Leave the code better than when you started
* Simple > Complex, Single responsibility principle
* Code is read more often than it is written
* Not Invented Here
* YAGNI
* SOLID
* DRY


Our mission statement across all projects is to deliver high-quality, maintainable, robust applications, and our technology stack is built with that in mind. This does not have to mean “playing it safe” and always sticking to what we know; our industry is one of continuous evolution after all. If you feel there is an opportunity to explore something new in a way that expands our horizons while respecting the client’s best interests, your voice will always be heard. 

Talking specifics, we love Ruby as a backend language for its developer friendliness and expansive community. Rails as a framework is perfect for rapid prototyping while retaining suitability as a production solution. It has been a proven performer for us for many years, and allows us to deliver great products to our clients and their users quickly and effectively. On the frontend, we are huge fans of React for delivering high-performance interfaces which are as much fun for the engineer to work on as they are for the user to experience.

We also regularly undertake internal projects which create opportunities for us to experiment and evaluate, and build confidence with new tech options we may later roll out to our clients.

* The right tool for the right job
* We love Ruby - quick progress, quicker to launch, quicker to user feedback
* React and React Native
* Not beholden to any technologies / we like exploring new technologies

* Everything we do is version controlled with Git
* Empowers cross developer collaboration
* GitHub Workflow, consistent across our projects
* Auditable decision log for our work

Code review is a key part of the process here at Kyan, driving improved
quality in the solutions we build. This shared responsibility for quality helps
to ensure a level of consistency within our projects, leading to better maintainability, and
improved team cohesion.

While we should always aim to adhere to the broader principles of our
[engineering philosophy](#engineering-0), we don't believe code review should be a dogmatic process,
and encourage discussion as a means to achieving the best possible results, rather than strict
adherence to a specific way of doing things. It’s about making our code better together, not fighting over single vs double quotes!

Perhaps most importantly, we see code review as a natural opportunity for peer-to-peer learning, at
all levels within the team. Sharing knowledge is a key part of improving the health of a codebase,
and of the engineering team in general, and constructive comments are always welcome.

Code Review is something of an art in and of itself, and there are a wealth of online resources dedicated
to just this topic. These are some of our favourite resources focussing on this, which we recommend
going through to all of our engineers:

* <a href="https://www.youtube.com/watch?v=PJjmw9TRB7s" target="_blank">RailsConf 2015 - Implementing a Strong Code-Review Culture</a>
* <a href="https://google.github.io/eng-practices/review/" target="_blank">Google Engineering Practices - Code Review Developer Guide</a>


Automated testing is the backbone of all the engineering work we do at Kyan, and we aim to never
consider work complete unless it is covered by automated tests.

Code backed by high, meaningful test coverage is easier to update, upgrade and refactor, and allows
for frictionless handovers when bringing in new engineers or passing on work to another member of the team.

Through writing well tested, self documenting code - complete with intended uses cases and working
examples - we ensure the meaning of the code and the intent of the original author is conveyed every time.

When starting a new piece of work, we use a Test Driven Development (TDD) approach, giving consideration
to how it will be tested from the very beginning. This drives simpler, better defined code, with narrower responsibility.

When working on older code with less than ideal test coverage, our key consideration is to leave the
code better than we found it, at a minimum writing tests to cover the new behaviour being added and,
if time allows, adding examples to cover existing functionality as well.

Feature / system tests are the most valuable tests, focusing on behaviour the system externally,
rather than implementation. They are also the hardest to write and maintain, the most brittle and
are slow to run. Unit tests are the opposite, focussing on narrow scenarios. They are easier to
write and maintain and are faster to run. At Kyan we use a mixture of feature and unit tests, starting
with feature tests to give a broad quality coverage and then using unit tests to focus in on parts of
systems that require many and / or more complex scenarios, where equivalent feature test would be
impractical.

Test coverage offers a useful metric of the scope of a test suite, but offers no insight into the
quality of the tests it contains. It is easy to write tests that cover large sections of a codebase,
but without thought of meaning, no test will give the benefits discussed here. With that in mind,
high test coverage is the beginning, not the end of writing high quality tests, and the tests we
write reflect that philosophy.


Our go-to testing framework for React applications is React Testing Library (hereafter RTL), the brainchild of Kent C Dodds. The guiding principle is to simulate user interaction and then test against rendered output.

Taken straight from the RTL website: The more your tests resemble the way your software is used, the more confidence they can give you.

### Our Principles

#### Test use cases, not code

The greatest benefit from RTL is arguably its philosophy of testing, and this is something that we’ve really bought into. We’re looking to ensure our products work for the user, rather than testing whether our code works in a particular way.

This philosophy solves issues with previous JS testing frameworks, whereby testing implementations could become incredibly verbose and/or complicated, to the point that developers might feel the need to change the code to create a satisfactory test.

Testing use cases also allows developers to rethink entire implementations, and still be able to rely on their tests to tell them that they haven’t broken anything.

#### Help out the next developer

Tests should be written as simply as possible. The purpose of a test is to quickly show where there is an issue with a new piece of code. As often as possible, we should:

* Write our tests in plain English.
* Maintain a common and easily understandable structure (Setup, Render, Interact, Assert).
* Present as few barriers as possible to the next person to read them.

There is no need to save bytes, or to abstract for the sake of abstraction. Individual tests are far more useful when they contain all of the information that is needed to understand a failure.

This approach helps developers of all levels of experience get onboard with testing.

There are exceptions to this rule; in cases of severe repetition or particularly long test files, it may make sense to use the [before* functions](https://jestjs.io/docs/setup-teardown) to setup your test data/mocks, or even to move this to the top of a test file. Generally speaking, we should avoid moving this to other files and especially should avoid sharing setup between test files.

#### Don’t test when you don’t need to

Be wary of testing code that’s outside of the scope of a test. 

* Any third-party code (plugins etc) is outside of the scope of your tests.
* Mock children and utilities where necessary to avoid testing other parts of your codebase unnecessarily.

#### Coverage

Within the JS testing community it’s generally accepted that 100% coverage is not necessary. Roughly 70% - 80% coverage is perfectly adequate; the returns are diminishing for anything more than that.

### Testing in Practise

#### Testing structure

When writing tests we’ve tried to use a common pattern within our \`it\` blocks as a guideline. The general idea is to create a story that future developers can read and quickly understand:

* Setup - Create any mocks or test data.
* Render - Using RTL’s render method, set up the DOM for the test.
* Interact - Exactly as a user would, interact with the rendered components (using the userEvent package makes this simple).
* Assert - Write your expectations, testing against the visual changes that the end user would experience.

#### What should be tested?

It can be difficult to know how far to take tests, but if in doubt, there’s a couple of ways to think about what you’ll need. 

Most pieces of work at Kyan are written with a set of well-defined acceptance criteria, which you can use to write your test descriptions. This lends itself to thinking about testing use cases rather than code.

But if all else fails, think about this maxim from Kent C Dodds:

> “What part of this app would make me most upset if it were broken?”

#### Snapshots

Snapshots are a simple way to get test coverage quickly. A snapshot is a representation of the state of the DOM at the time of render. Every time you run a snapshot test, it will compare a saved snapshot with the new render.

There are a few problems with snapshots however:

* Tests will fail until a new snapshot is recorded, even if the change was expected or (in the case of purely presentational changes) does not affect functionality (false positives).
* Changes in child components will also unnecessarily cause snapshot failures in any parent components.
* It’s far too easy to update a snapshot for passing tests.
* As complexity increases, snapshots become larger. They can be difficult to read, and add unnecessary bloat to your repo.

Which is not to say that you shouldn’t use them. Snapshots are still useful for simple components with very little (or no) logic or user interaction.

#### Unit Testing vs Integration Testing

Generally speaking the tests that are written with RTL are unit tests, meaning they test distinct pieces of functionality. 

We have experimented with using “template” components that compose other components, allowing us to do faux- integration tests.

For the moment though, we’ve accepted that unit testing is relatively new for Kyan, and are e=not immediately looking to introduce integration testing.

#### TDD

Test Driven Development is something that individual developers have experimented with, but it is not a requirement for any of our projects. If this works for you, or you wish to add it to your repertoire, go for it!

Regardless of whether you want to use TDD, it is valuable to start thinking about tests early; to that end you can start by reviewing acceptance criteria for a ticket, and writing placeholder test scenarios before writing any actual code. This helps you consider more about the component you're building ahead of time, but without the overhead of writing the entire tests.

### Best Practise

#### userEvent Package

Use the \`userEvent\` package for interacting with the DOM. 

> \[userEvent] is a companion library for Testing Library that provides more advanced simulation of browser interactions than the built-in fireEvent method…

The API is incredibly straightforward and as of yet we haven’t experienced any issues in using it. It is considered a [common mistake](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library) not to use it.

#### Queries in RTL

There are a [variety of queries](https://testing-library.com/docs/queries/about) provided by RTL for asserting your expectations. It is generally accepted that there is a hierarchy of importance in these methods.

Queries that are concerned with accessibility are generally considered the most important (getByRole, getByLabelText, getByTitle). These are highly recommended as it helps reinforce a development team’s focus on accessibility.

After that, come the queries that more broadly test the rendered markup (getByText, getByPlaceholderText).

Finally, there’s getByTestId, which is a perfectly acceptable query to use (at some point you absolutely will need it). The reason not to use it is that a user will never have any conception that a test id exists; it goes against RTL’s idea of always testing against what the user can actually see.

#### Use Regular Expressions in Queries

You can [use a regular expression](https://testing-library.com/docs/react-testing-library/cheatsheet/#text-match-options) to make your selectors more resilient to small UI changes.

```
// Component

<button>Download Your Illustration</button>

// Test File

getByRole("button", { name: /Download illustration/i })
```

### Resources

* <https://kentcdodds.com/blog/common-mistakes-with-react-testing-library>
* <https://kentcdodds.com/blog/testing-implementation-details>
* <https://kentcdodds.com/blog/how-to-know-what-to-test>
* <https://testing-library.com/docs/queries/about>

* Ensures all of our automated testing and linting is run before any changes hit production.
* Humans make mistakes.
* Improves quality.
* Makes code coverage, and other codebase health markers visible to the team.

Quality assurance testing is the process of ensuring that the product is of the highest possible standard for the customers. As a QA team, it is a must that we maintain the highest possible quality for our products. Here are some best practices to help the QA get the most from the testing strategy. 

#### Understand business goals and make Acceptance Criteria clear

This is the cornerstone of a project and should be clarified before the development starts. The project team has to understand what should be done, who the target audience is, and when to know there is nothing left to do. To do that the ***QA should work closely with the product development team.*** Understanding business goals helps the QA to define the acceptance criteria so that the ***requirements become clearer, more understandable and testable***. As a tester, it is a must to review and discuss the requirements with the development team right from the start. 

#### Writing good test cases

Once requirements have been established, tests can be built with confidence. High-quality tests help the QA to determine whether the system under test (SUT) functions as it should based on the acceptance criteria. Test cases make the testing more efficient because they can re-run the same tests on subsequent builds without rewriting them. 

* ***Create tests with a purpose***
* ***Create clear and necessary steps***
* ***Avoid too many dependencies***

Break down each test case into a series of concise steps. Taking these steps will tell the QA whether or not a feature works. QA can think of writing a test case as a series of actions associated with a question. When an action is taken, the automated test or human testers should answer a simple question to measure the success of the action. Make sure the QA keeps the Test Cases/Checklists up to date. Currently all the test scenarios/cases are written on Google sheets. 

#### Engineer foolproof testing

Before QA begins testing, ***make sure the SUT is stable and testable*** so that the QA doesn't lose time retesting. QA needs to check if the build has adequate core test data and if it doesn’t then the QA needs to communicate this with the project team and get it sorted. Only when the QA has a testable SUT then the tests serve their purpose and work properly. 

#### Combining test automation and manual testing

Manual testing allows the QA to cover a wide range of conditions and scenarios. The feedback of the QA testers regarding the experience and feel of the app prove invaluable. ***Manual tests are preferable for exploratory testing, usability testing and ad hoc testing***. Ideally, manual tests should be performed by highly skilled and experienced testers who represent different end user profiles and use a wide range of devices and operating systems.

* Incorporating Exploratory Testing : The main purpose of this testing is to understand the product better and take a look at it from a user’s perspective.

To save time whilst testing, manual testing can be supplemented with frequent automated tests. Automation won’t be a good fit for all the testing needs however any test that needs to be performed repeatedly should be automated. Automated tests are practical and reliable and will help the QA to make sure the app performs as expected from a technical standpoint. 

#### Share QA status report with the clients/team

QA status is the document prepared by the QA team for clients or for the project team containing actual information about the project. Which features were completed in the particular sprint, what is still in progress, what are the known issues, which demo build was used for testing. QA always prepares the release status by the end of the sprint. ***This gives the clients additional transparency about development progress***. 

Template for the QA Status report: <https://docs.google.com/spreadsheets/d/1k4SiPBxVlFS_JBJDv3eLCOIIwAyeAM5U/edit?usp=sharing&ouid=113938238710082967598&rtpof=true&sd=true> 

#### Share domain knowledge with the team

Each QA brings a different set of skills and talents hence sharing the knowledge and talents can help fellow QAs to improve their own challenging areas. This can be done by setting up weekly or monthly catch-ups with the team.

We pride ourselves on having a friendly, supportive culture where egos are left at the door. We believe that being a great engineer isn't about knowing the documentation by heart; it's about having a positive, inquisitive approach to problem-solving and backing that up with open and honest communication. The job is a continuous learning process for all of us, and asking questions or sharing insight helps us level-up together as a team.

In addition, we also believe it's tremendously important to harbour a blameless culture. All our code is peer-reviewed and passes through QA; if something goes wrong we don't launch a witch hunt to find an individual at fault, instead we try to analyse and understand our process better so we can help avoid similar situations in the future. We are all on the same side here, and nobody is perfect - finger-pointing is out of the question!

If one of the team has a topic they feel particularly passionate about, or has been playing with something new (or old) which they think is cool, we warmly welcome dev talks which we make an effort to hold as regularly as possible. These can range from short 10 minute lightning talks all the way to full hour presentations, so no subject is too big or too small. Similarly, if someone has something they're itching to share, but they're not comfortable speaking in front of a group, we also have a blog our engineers can either write for directly, or have a short interview which we'll then craft into a post for them. One way or another, we do our best to give a voice to everyone on the team with anything interesting to share!


Our speciality at Kyan is developing quality applications, but a great product is nothing without first-rate hosting to deliver it. That’s why our preferred approach is to let third party specialists take the operational load, so that we can focus on features, maintenance and keeping a product-centric mindset. Platform as a Service partners such as Heroku are our favoured approach, but if that is not appropriate we work with our clients to settle upon solutions which meet their needs without compromising on quality.

Locally, we have been using Docker to standardise development environments for a number of years and have found it to be absolutely invaluable. It takes the pain out of project switching and means we can spend less time debugging fiddly configuration issues and more time on the fun stuff, making great software!

* Docker for local for efficiency, cross project niceness, etc.
* Favouring 3rd party specialists so that we can focus on application development and maintenance
* Quality hosting is just as important quality development
* Security is everyone’s responsibility

## Engineering Roles

### Junior Software Engineer
With support from the more senior engineers you are passionate about learning and developing your skills, open to exploring new techniques and best practises. Having typically less than 2 years working as an engineer in a professional environment

### Software Engineer
An accomplished engineer with 2-5 years of experience in a professional development environment as a Junior Software Engineer, with strong technical experience you are looking to develop your skill to a higher level.

### Senior Software Engineer
A driven software professional eager to build on your already extensive knowledge and experience. Typically with 4-5+ years experience working in a professional software development environment you take a natural lead on projects and bring a wealth of technical knowledge to the table.

### Solutions Architect
Typically 5-8+ years working as an engineer in a professional environment, Solutions Architects exhibit leadership skills and a wider influence within their teams, with a particular emphasis on technical stack, delivery and support.

### Team Lead
From helping to define engineering processes and best practice, through to aiding the growth of your fellow team mates, you are a technology expert who is driven to improve both your particular specialism and the wider department as a whole. You are passionate about growing not just your own knowledge but also that of others within Kyan so that we are the best Engineering Team possible.

Everyone’s responsibility, but inherently there’s a lot of technical considerations.


* Workshops run by engineers for engineers
* We have experts in many areas, let’s share the knowledge
* Dev meet (see culture)
* Continuous learning environment
* We can all grow and improve with the learning/teachings of others in the team
* Conferences and meetups
* Pairing when it makes sense


Loading…