Add guidance on Performance

[barrymcgee]

Done

• Added some guidelines around web page performance

QA

• Sanity check Performance guidelines
• Add points I missed or suggest corrections as you see fit 🤓

[nottrobin]

This is a really great contribution. Do you think you might want to make it a blog post?

I've been thinking about what sort of thing should go into practices. Ideally I'd like practices to be really concise & specific, deep statements, with real implications about how we work in our team. I think it would be best not to repeat existing best practice, but rather link to it. This is so Practices can be useful, easily consumable, and our stronger statements about genuine team positions won't be diluted by pages of general advice.

I've been exploring this idea here: https://github.com/canonical-webteam/practices/issues/148

So I think general best-practice advice on things you should generally think about when optimising for web performance should maybe not be in practices. A list of well known performance techniques doesn't need replicating in our standards.

I think your short introduction is closer to what I'm thinking about as practices - "We should treat performance as design - it's not an optional enhancement" is maybe still a little fuzzy, but it does allude to a specific team attitude to performance, which is gold. But then it should simply link to a list of "techniques we should consider to mitigate their cost", rather than include the list.

I do think what you've written here is really great. Under my suggested model, I'd suggest this sort of content would be better either published as a blog post or simply as a Wiki post (or maybe, initially a Wiki and then later a blog post when you get around to it - as I did with my Git tips), and then be linked to from a shorter, more declarative set of statements about performance.

But parts of your advice that could be contextualised to provide specific advice for our team and our sites might be useful as practices. For example, we can do better than mentioning that WebP is a good format. We know WebP isn't supported in IE or Safari, but that we do support those browsers. And so we could make a strong statement about what we do about this problem - do we not use WebP? Or do we have a specific technique or set of techniques that we recommend? E.g. Cloudinary.

Similarly, I think many of these statements could be useful as practices if they could be changed (and agreed) from fuzzy statements about "you should maybe think about this" into strong statements that genuinely denote the position of the team, as separate from general best practice. For example, if we had specific team-agreed red lines about third party scripts, or even specific third party scripts that we accept, or prohibit.

Of course, my desire & interpretation of what Practices should be is still only an idea. So if people disagree with me about the nature of Practices, I'm happy to be overruled.

[nottrobin]

If you agree with me, then a quick way forward could be simply to move your whole "## Performance considerations" section to the Wiki, and leave this document as just the introduction, but with a link to that Wiki post.

[barrymcgee]

@nottrobin I don't disagree per se but it sounds like you'd prefer if this repo was a set of principles rather than a set of practices?

I didn't even know that wiki existed - the trouble with scattering information like this over several locations is people invariably forget where all the disparate resources are.

I'd rather save the blog post for when I've made some tangible performance improvements one of our sites and then write about how that was achieved.

[nottrobin]

it sounds like you'd prefer if this repo was a set of principles rather than a set of practices?

I want it to be both, I think - it's both statements about how we work in practice (e.g. "we use Prettier") and guiding principles to help our team make decisions (e.g. "We aim to support and grow the communities that surround our work.").

But in both cases, these statements are opinionated - they specifically state a choice we make as a team that is different than a choice another team might make. They aren't general advice for how all software developers should work, or simply reiterations of existing advice that exists elsewhere.

We do, unfortunately, currently have replicated general advice, but I'm suggesting we should stop including that sort of content in practices, and keep it elsewhere instead.

I didn't even know that wiki existed - the trouble with scattering information like this over several locations is people invariably forget where all the disparate resources are.

Yeah I'm suggesting we make that wiki a thing. We have https://wiki.canonical.com/, but that's private, and I'd like there to be a place for publicly available wiki posts.

But anyway, if you link to the article from a page in practices, it's just as findable as if they were in the same article. Obviously there is the danger of link rot - but as it's another closely located space that we control, we also have control over the link rot.

I'd rather save the blog post for when I've made some tangible performance improvements one of our sites and then write about how that was achieved.

I think this would be a great blog post in and of itself - distinctly different from, and maybe more useful, than a post about how we actually improved performance. Although we should write that one too. I really don't want the barrier to publishing blog posts to be high, and this really would be a great addition (maybe with a couple of links to some sources).

[nottrobin]

Yeah I'm suggesting we make that wiki a thing. We have https://wiki.canonical.com/, but that's private, and I'd like there to be a place for publicly available wiki posts.

Or we could try to get a team area on the Ubuntu wiki: https://wiki.ubuntu.com/Teams

[nottrobin]

:+1: from me, I guess we should decide the nature of practices separately, and apply it broadly.