canonical-web-and-design / practices

Guides and principles from the web team at Canonical and Ubuntu

Web and design team practices

A collection of documents that describe best practices for Canonical web team.

These can be also be viewed at https://canonical-webteam.github.io/practices/.

Run site locally

This site is built using Jekyll.

To run this site locally, you'll need to first install Ruby on your local machine.

Once you have installed Ruby, you can then install Bundler by running;

gem install bundler -v 1.17.3

The next step is to install the Ruby gems required to run the site with Bundler;

bundle install

You can then serve the site using Jekyll;

jekyll serve

...which should open the site locally in your browser at http://127.0.0.1:4000/practices/

Contributing

For guidelines on contributing to these documents, see CONTRIBUTING.md.

Code formatting

This code base uses Prettier to ensure consistent formatting.

To run Prettier over the code base (assuming you have yarn installed), run:

yarn prettier-write **/*

Troubleshooting

Jekyll not found

If you encounter a problem when trying to run an installed gem, that states that it can not be found, make sure that the directory in which gems are installed is included in your PATH. You can verify this by typing echo $PATH in a terminal and checking for the folder in the output. If you are not sure what folder your gems are installed into, run gem env | grep EXECUTABLE\ DIRECTORY and add the path that is printed into your PATH environment variable.

License

The content of this project is licensed under the Creative Commons Attribution-ShareAlike 4.0 International license, and the underlying code used to format and display that content is licensed under the LGPLv3 by Canonical Ltd.

practices's Issues

Blogging

• How to publish blog posts
• Getting it reviewed
• Where to publicise your blog posts
• Blog posts should be scheduled in backlogs

Which badges to use?

I like putting badges on our repos. The obvious ones to have for every repo are CircleCI and Codecov.

Other ones we could consider:

General

• a good-first-issue counter
• david-dm for NPM dependencies
• Something for our requirements.txt dependencies

Websites

• uptime from https://uptimerobot.com/
• find a way to automatically display the version of Vanilla Framework we use?

Packages

• latest stable release version
• semver version
• package downloads

What do people think? Are these valuable? Should we use any others?

Update CONTRIBUTING.md to reflect code-style PRs

E.g. see https://github.com/canonical-webteam/practices/pull/99#issuecomment-440306872

Document agreed unit values for Sass

Document the agreement from the following:
canonical/vanilla-framework#854

Convert into a GitHub pages static site structure

Mention that sites should always be deployable from master

If it's not already mentioned somewhere.

Document the responsibilities of squad leads

Some suggestions of such responsibilities:

• Explain the required elements that must be presented in the squad's Backlog spreadsheet
  • Tasks in the current iteration
  • Status of tasks
  • Points? Maybe not?
• Define the meetings before which the Backlog spreadsheet must be up-to-date:
  • The "end-of-iteration demos" meeting
  • The "management iteration planning" meeting
  • The "scrum of scrums" meeting
• Prepare (and email around?) a 1- or 2-paragraph summary of what the squad achieved in the last iteration. These paragraphs can then be included in the email / blog post that the design team put out about the completed iteration.
• The internal running of the squad, the planning meetings, management of tasks etc., is up to the individual squad lead. But also suggest some patterns:
  • Pre-planning and planning meeting
  • Retro meeting
  • ZenHub? GitHub projects? Whatever you like?
  • Suggested kanban board lanes
  • Suggested stand-up format
  • Using points and velocity?

We should use the HTML data attribute to target elements using JS

This approach means that we have clean separation between attributes used for JS interaction and attributes used for styling.

Supporting:

• https://toddmotto.com/data-js-selectors-enhancing-html5-development-by-separating-css-from-javascript/
• https://emilien.klein.st/posts/using-data-hook-attribute/

Note:

• There is a slight performance penalty for using data attribute selectors but, even for a very high number of selections, this is negligible in absolute terms: https://decadecity.net/blog/2013/07/04/using-data-selectors-for-javascript-functionality

Document standard CI tests

Thing we should test in all projects:

• sass linting
• flake8
• pa11y
• percy maybe?
• link checker
• HTML validation

And then any unit tests, of course. But that's just nice to have

Meetings

Lifted directly from @pmahnke's slides:

Fewer meetings

• Try to book meetings in the afternoons - keep mornings for work
  • Please re-do the calendar
  • Move meetings out of Babbage, Cerf, Dijkstra
• Only have a meeting if really you need one
• For the invite
  • Only invite who you need
  • ACCEPT or DECLINE the meeting
  • Check that required people can attend
  • Add a video link and a description
  • Make the meeting MODIFIABLE
• And remember, meetings don’t have to last the full amount of time

Better meetings

• Have an AGENDA
• Take NOTES and share them
• Have ACTIONS/DECISIONS
• If using a video or presenting ... show up early to get everything working

Someone please convert this into a practice document. Maybe @matthewpaulthomas would love to do this? =)

Write git review checklist

including thinking about:

• - removing now-redundant code
• - properly namespacing, encapsulating code

Code-Formatting Page JS heavy

https://canonical-webteam.github.io/practices/coding/code-formatting seems very focussed on JavaScript.
Should we move the first sentence:

To ensure consistency across our codebases, we utilise Prettier.

into the JavaScript block?

How about keeping Code-Formatting rules in the respective language documents => Maybe quicker to find the info for the language I am looking up?

Merge react.md into a generic document about JavaScript guidelines

Rationale here: https://github.com/canonical-webteam/practices/pull/106#discussion_r235654424

actually most of the recommendations in this document should be generalised as JavaScript guidelines - naming of component files and JSX files should probably sit alongside general advice for naming JavaScript files, that advice and advice on Redux could also be applicable in non-React apps. So what should probably happen is that any React-specific advice should form a section in a general document on JavaScript advice.

Document standard test policy

This document should answer those questions:

• What should we test (complex functions?, long functions?) ?
• Unit tests vs Integrations tests, e2e tests (:+1::+1::+1::+1::+1: )
• How should we test (libraries)?

Should every 404 pages return search results?

I realised that this is quite a nice experience (although wording could possible be improved):

https://jujucharms.com/ksplice/

Should we aim to do this with all 404 pages, as long as the site has search? We could start with www.ubuntu.com. Or maybe even if the site doesn't have search we could iframe in some Google search results or something?

Add `is-active` class to active link in sidebar nav

The styles are already in styles.css so just need to add is-active to the relevant anchor

Tests optional?

In the python standards doc that just landed, we state:

Although tests are lacking on many of our existing projects, writing tests is strongly encouraged. Please write tests for any new code if at all possible, and any efforts to improve test coverage on any project would be greatly appreciated.

This is a bit at odds with Canonical engineering culture. We should never land code without tests where feasible. If there are technical reasons making it difficult to write tests, we should discuss those and find a solution. Maybe this would be a good discussion for the next dev catchup?

Lack of menu padding on "foosball" and "podcasts"

In the navigation, there should be more padding between "foosball" and "podcasts" and the items that are listed underneath

Add examples to the estimation guide

I do want to make sure examples are added, because I think most of the words used here are very much open to interpretation without some concrete examples.

Add standard ranges for z-index

Suggested ranges:

• 0-50: Core website content
• 51-100: Other plugins
• 101+: Reserved for the core website to overlay plugins if needed

We could also recommend keeping z-indexes organised with a Sass z-index map (thanks @anthonydillon)

Document common QA steps to do when reviewing PRs

See dev catch-up notes

Do we need autoprefixer?

@hatched asked the question - do we still need autoprefixer?

All the major browser vendors have made statements about reducing reliance on vendor prefixes:

Vendor Prefixes Are Fading

Luckily, it appears vendor prefixes are fading away as browser teams look for better solutions. The Chrome/Blink team have adjusted their approach:

“Going forward, instead of enabling a feature by default with a vendor prefix, we will instead keep the (unprefixed) feature behind the “enable experimental web platform features” flag in about:flags until the feature is ready to be enabled by default.” – The Chrome/Blink team

The Firefox team are also on their way to a similar approach:

“For what it’s worth, the current trend inside Mozilla is […] avoiding vendor prefixes by either turning things off before shipping or shipping them unprefixed if they’re stable enough. At least
as a general policy; specific cases might merit exceptions.” – Boris from Mozilla

Microsoft Edge aims to remove support for prefixes altogether:

“Microsoft is also getting rid [of] vendor prefixes for Edge. This means that in order for developers to take advantage of special HTML5 or CSS features, they won’t have to use a specific Edge prefix. Instead, they can just code to web standards.” – Mashable

And in practice, the number of prefixes for standard features is fading fast. There don't appear to be any -moz-prefixed pre-standard properties any more, and there are only a small number of -webkit ones.

Although e.g. http://shouldiprefix.com/ still claims you need prefixes for important properties, caniuse.com disagrees - e.g. animation, background-clip, filter, display: flex, display: grid, transform.

Of the browsers we care about, here's a list of basically all of the things vendor prefixes still help with, at the time of writing:

• appearance in Webkit browsers and Edge
• maskin Webkit browsers and Edge
• filter in Edge
• object-fit in Edge
• grid in IE11
• flex in IE11

This list is very short. And appearance, although technically now a standard, is basically purely proprietary, so we probably wouldn't want autoprefixing for it anyway.

mask may well be useful. But do we currently use it?

I'd argue that filter and object-fit support in Edge are hardly centrally important features (Edge comprises 3.86% of our traffic in the most recent analytics).

If we want to support IE11 properly then display: flex and maybe display: grid may be important, but if it's literally just these two properties that need vendor prefixes, running an autoprefixer in every project seems overkill. We could probably just explicitly declare prefixes in just these 2 cases. We could apply the same logic to the mask property, if we use it.

What do people think?

Document Sass module name spacing

Document how html forms should be marked up

There are html guidelines but no best practise for forms.

Stand up practice

Stand up, or in other words scrum, is a short meeting that team uses to communicate progress to each other. It's done daily with all team members of a squad present either in the office or online.

Standard format of a stand up:

• go through the board card by card giving an update on the progress of each of them

Each squad must have a stand up every morning with an exception to management meeting and end of iteration demo days. The maximum time a stand up should last is 15min, however some teams use less time. Also stand ups should happen each day at the same time, they don't get postponed, even if a team member is late.

The reason behind standing up during the daily scrum is to keep the meeting short and to the point for that reason also stand ups don't include full fledged discussions.

Stand ups should be conducted on the big TVs in the office. Each squad is set up on both of them including their zenhub board, backlog and Google Hangout/ appear.in link

What's expected at the stand up?

• questions about the progress/ state of the work
• questions about the state and quality of task cards and epics
• questions about dependancies between various task cards

What should you prepare before the stand up?

• make sure your task cards are updated and are in correct columns
• make sure you know the latest state of your work e.g if you're waiting for a review to come through
• make sure you checked your emails so you know if anything that might impact your work came through over night
• make sure you update your team on early leave or similar events

Tips from the PM:

• if team members get involved into a lengthy conversation ask them to stop and continue the topic after stand up with only relevant people needed in the discussion
• if you're having trouble with the TV, inform your PM and use your laptop in the meantime

Mention rel=presentation in IMG guidelines

Document practices around meetings

Document practices around meetings, with some mention of philosophy. Are we for or against solving issues through meetings vs e.g. emails? Some ideas:

• Every meeting should have a description, including expected outcomes
• Every meeting should have meeting notes, emailed round of published in https://github.com/ubuntudesign/meeting-notes/issues
• Before starting a one-off meeting consider whether it's still needed - feel free to cancel the meeting if it's not needed (don't skip regular process meetings - demos, retros, dev catch-up etc.)
• Feel free to shake it up and leave the office for a meeting =)

Codify practices to encourage blogging

We need to blog more. We should put standard practices in place somewhere to encourage this:

• Maybe an official agenda item in a process meeting?
• Actually add and prioritise blogging and writing practices in backlogs
• Maybe set a blogging requirement for each squad?

Document python coding standard

There appear to be conflicting ideas on some styling.

As a casual pythoner I'd appreciate some form of guidance.

Web "& Design" team

We are actually the Web and Design team - we should be inclusive in the website (and repo!) title
#designtoo

Team Off-Site Meeting 12/12/2017 - Notes & Actions

On the 12th of December 2017, the team held an off-site meeting at the Ace Hotel in Shoreditch to discuss the process, strategy, and to have a bit of fun. We first voted on the topic we wanted to talk about, and then chose the 4 most popular topics and held retros. The topics were: Using evidence to improve our websites, MVP thinking, Design threads, and Pastoral care

The notes from the off-site have been included below, with the important actions in bold.

Retro 1 - Using evidence to improve our websites

User Testing

• The team discussed whether it would be feasible to do testing before big decisions were made. A potential solution would be to create low-fi prototypes and test those.

• The team agreed that stakeholders need to know about the purpose and value of any tests we run, including the end goals, metrics, etc.

• The team raised a concern that finding valid users for testing purposes was hard because of our very niche products. The team explored the use of hallway testing - building relationships with customers/community while at events & conferences. By doing this, we can find the right people, build a database of valid testers, and remote test our products with them.

• The team thought that currently stakeholders do not understand the value of qualitative data, and are only concerned with quantitative data. We need to show stakeholders the quantitative data (e.g. from AB tests), and then use this data to explain and justify running more detailed tests that would result in qualitative data.

Dashboard

• The team thought that it would be beneficial to look at analytics through Dashboard in order to check page views, download numbers, etc.

• Squads need to use Dashboard to define KPI’s

• Each Squad should have a meeting about KPI’s and dashboard.

AB Testing

• We need to define meaningful goals for AB tests

• We need to define the expected user journeys

• We need to then validate these user journeys against analytics gathered from AB tests

Site Build

• Ensure GA actions and events are implemented on anything that is worth measuring

• The team identified that there is a trade-off between site performance & GA events, therefore events should be on elements that we definitely need and want to track.

• Squads will have a meeting about GA events - what UX’ers want to track

• The team identified that the site speed varies greatly worldwide, for e.g. it is slow to load in places like China & India. The developers will have a meeting to discuss worldwide site performance & speed

Extra thoughts

• We need to be careful of what we “target” and consider a “metric”, as it might have a negative effect on the overall experience.

Retro 2 - MVP Thinking

Planning

• We need to measure the success of MVP’s or “phases” by testing them and analysing the data

• The squads need to define what is the most “viable” product. An idea is to define this in the planning meetings while discussing the work.

• The team wants more mini sprints for certain epics. In planning, we should look at features and decide what the best way to tackle it is: within the 2-week iteration or a mini sprint

MVP / Future Vision

• The team wanted more one-day “future design” workshops/sprints to find out the bigger picture, and to also identify the MVP’s, and use this information to communicate with engineers

MVP as a research tool

• We need to tie MVP’s into testing

• The team discussed that we need to improve our communication with stakeholders about what is the MVP, and then show them the longer plan too

• The team identified that when an MVP is developed, it is a good time to do user testing

MVP in Demo’s

• The team discussed that we should utilise testing data when we are presenting work at the demo meeting. For example, if we are showing a version B of a homepage, we should show the data of the A/B test to discuss which version is better.

Retro 3 - Design Threads

GitHub “Team Discussions”

(You have to be a part of a “team” to access the GitHub team discussions)

• A stickied post can contain a link to the spec, as well as a refined summary of the discussions, had in the forum thread

• Members of the discussions forum can link to specific cards when discussing topics

• A lot of the team were keen to keep design threads on Git. “Github Team Discussions”, a new forum-like feature on GitHub, was proposed, and the squads have agreed to try it. Find out more here: https://github.com/blog/2471-introducing-team-discussions

Proposed rules for team discussions

• It should be easy to see finished and agreed designs

• Should be open to the community

• The history should be preserved

• It must email (alert) people

Retro 4 - Pastoral Care

• The company needs to be more transparent on things like training & team budgets

• More healthy snacks in the kitchen (not just fruit!)

• Daily yoga meetup

• More structured fun (pub of the week, etc.)

Squad leads off-site: actions

On Tuesday 7th November we held squad leads off-site meeting with all squad leads in attendance (Karlos, Francesca, Maria, Martin, Carla) and Peter, Kasia, Shivam, Ant, Robin.

The objective of the meeting was to conduct a retrospective on current process, celebrate successes and come up with a list of improvements. The idea is to implement the improvements and review them in 3 months. The following actions came out (in the order of the discussion with zero actions topics listed at the end):

Briefs:

• For management of briefs send a brief to Kasia, she'll upload it to the folder for briefs and update the backlog - owner: squad leads

Meetings:

• UX catch up every 2 weeks is needed - owner: Carla
• Add meeting descriptions and "at the end of this meeting we will..." to all meetings - owner: squad leads
• Have meeting notes after meetings - owner: everybody
• Limit the number of open laptops and use of phones in meetings - owner: everybody
• Meetings in the afternoons are good - owner: everybody
• Split progress update from demos to a separate meeting, investigate - owner: Peter

Stand ups:

• Stand up format is to go through cards - owner: squad leads

Planning:

• Estimate tasks - owner: everybody
• Training on how to estimate/ conversation with Carla - owner: Ant
• In estimation session look retrospectively at previous estimations and compare (find formulas) - owner: everybody
• Calculate (plan for) extra time before working on a feature and write a brief for it - owner: everybody
• Keep maintenance epics - owner: squad leads
• Macro planning for product squads - owner: Kasia

Scrum of scrums:

• Ask for help in scrum of scrums - owner: squad leads

Backlog:

• Epics must be created when work get scheduled for an iteration - owner: squad leads
• Beyond iteration track work as you feel is best, create epics for iteration - owner: squad leads

Zenhub/ Github:

• Create a pull request for changes to designs and merge once it's agreed, experiment with feature branches - Owner: Carla to trial, Ant and Robin to run a workshop for all designers
• Epics must be created when work get scheduled for an iteration - owner: squad leads
• Create cards before planning meeting - owner: everybody
• Get access to Zenhub for engineering managers - owner: Peter

Demos:

• Leave it to squad leads to demo - owner: squad leads

Miscellaneous:

• Nominate scrum master on an iteration basis - owner: squad leads
• Find ways to collaborate with stakeholders - owner: squad leads
• Tie our work to Mark's roadmap items - owner: squad leads
• Share backlogs with engineers - owner: squad leads
• Check that you're subscribed to webteam mailing list - owner: everybody
• Communication on what's the whole story (process) - owner: Kasia

Teams:

• none

Ideas we agreed not to implement:

• How do we make time for implementing actions from retro?
• Make cards for retro actions, invite external person to run, find a place for notes, get rid of Trello
• Training: how to schedule and make time for maintenance in an iteration?
• Stand ups - run from rooms or bring a laptop
• Delegate the responsibilities of a squad lead
• Standardise how we collaborate with stakeholders
• Demo presenting - from the middle of the room but only if people want to do that
• Demo finished work from the planned backlog list
• Estimating epics in t-shirt sizing format

Header does not fit on small screens

The header is to large on small screens. Maybe lose the text at a breakpoint?

Typo text "uneffected" instead of "unaffected"

Hello, I think I found a typo on Stylesheet Code Standard page in State Classes section. It is typed as
"uneffected" instead of "unaffected". Here's the image to show where the typo is

Double line on navigation

Great work on the site! Small piece of design feeback:

On Chrome 70.0.3538.102 on desktop, the line underneith the "home" and "Github repo" menu items seems to be two pixels high, where the rest of the navigation is normal.

Guidelines for community engagement

@anthonydillon, @carlaberkers, @clagom, @shivjoshi1996, @pmahnke and I recently discussed the possibility of having some community engagement guidelines in our practices.

I've been working on Discourse recently, and came across this, which I think is a good example to steal ideas from https://github.com/discourse/discourse/blob/master/docs/code-of-conduct.md.

Forking code, giving credit

Add an ethics point about how to give lots of good credit when copying anything at all. It will never hurt us to give thanks to others.

Meetings: pre-planning

Pre-planning, or in other words backlog gardening meeting, is a frequent squad meeting to organise, prioritise and clarify their backlog items. The objective of that meeting is to regularly organise the work in preparation for a sprint management meeting and sprint itself, improve knowledge of requirements and identify blockers.

Pre-planning meeting happens regularly each week, includes all members of the squad and lasts between 1-1.5h

What to do at a pre-planning meeting:

1. prioritise existing backlog items, if not possible due to insufficient knowledge:
2. take your time to understand each backlog item, read the brief, an epic or even a spec
3. think if all requirements of the backlog item are clear, do you need to ask for more information?
4. if a backlog item doesn't have a brief and it should, request it from stakeholders
   5.if a backlog item doesn't have an epic, create one with a title, description and link it to the backlog spreadsheet
5. check for new work requests e.g emails from stakeholders, new briefs coming in, bug requests, add them to the backlog and follow steps 1-5

Sometimes the team will be able to do steps 1-6 early in the process, other times it might take couple of pre-planning meetings to gather all required information hence the regularity of this meeting and a need to be proactive in gathering requirements.

Depending on a stage of an iteration the squad is in, it will introduce additional steps to the pre-planning. The week before next iteration (which is week 2 in scrum cycle):
7. the squad should identify the amount of points and list of deliverables they are willing to commit to in the next iteration
8. once the proposed for next iteration backlog items have been clarified and briefs/epics are done then they are ready to be split into tasks and estimated

Tips from the PM:

• when planning you next sprint deliverables consider any upcoming holidays, public holidays or in general out of office time
• if you need help with following the format or fitting into allocated time ask your PM to come into the meeting and facilitate
• if you're having trouble with gathering the requirements or clearing blockers escalate that to your PM

Create a shared repo where we can add cards for all squad retrospective actions

Summary

Currently each team has their own way of documenting their retrospective actions. Retro actions may involve across-squad collaboration, which will be promoted if the actions are visible to all teams.

Document how to create a design spec

We need to create a document which details how to create a design spec.

canonical/vanilla-framework#1113

Ownership and broadness

As mentioned in @pmahnke's presentation, we should enshrine in practices that people should take ownership and care about the wider context of work and the team. Expand your horizons etc.

Typo text "closeing" instead of "closing"

Hello, I think I found a typo on HTML Code Standard page in General Rules list. It is typed as closeing instead of closing. Here's the image to show where the typo is

Document the process meetings

Document what should happen in the shared process meetings:

• End-of-iteration demos
• Management iteration planning
• Scrum of scrums

404 vs redirects

Should we add something about best practices on this matter here?

Broken link on Canonical Web team's GitHub profile

Pardon me, I don't know where to report this issue to, therefore I create this issue here. So, here's what I found.

The link on Canonical Web team's GitHub profile is broken. It's redirected to a page which show 404 message. Here's the image to explain what I mean

Here's the page the link redirected to

Code of conduct / open source strategy

@yaili suggested:

Don't know if you've seen this https://opensource.guide/

I've had a quick look at it, looks good. I was wondering if we should add a code of conduct to our repo, and consider having a team page on vf.io.

Relevant sections:

• Your Code of Conduct
• Leadership and Governance

And @evilnick said:

Don't we already have a code of conduct? https://www.ubuntu.com/about/about-ubuntu/conduct
Maybe we should promote that more through repos etc.

Logo and favicon

Favicon currently missing.

For the logo should we use the Canonical logo? Or better Ubuntu? Or make something new?
The owl is cute but an out of date pictogram we are no longer using.

Be good to hear thoughts on this.

Link to home

Currently, the website has a "Home" link in the navigation and the Website title and Logo have no link.

In all our other websites (and general best practice on the internet) the title and logo link to home and the "Home" link in the navigation can be removed.

Add aria-hidden to pulled-in content

Also add tabindex="-1" to avoid an invisible tab trap.

Content like partners feeds, or RTP

More sharing, less snowflakes

This was mentioned in @pmahnke's slides - should we update philosophy to encourage more reuse and sharing and central services?