Getting agreement on big decisions, versioning prototype routes, pair writing

Getting agreement on big decisions, good reception for my new article, how making things open made things better (for me), and pair writing a new article.

Getting agreement on big decisions

I’ve been trying to help my team make a decision on whether the collection of services we’re responsible for should be separate applications that live on multiple (sub) domains or just a single application that lives on one (sub) domain.

There are different views within the team but we need to decide as quickly as possible. Fortunately, I saw Marc O’Connor’s talk about how to make sure the collective expertise is used within your team without pulling rank.

I could draw a number of parallels between Marc’s team’s problem and my team’s problem. So last week I began documenting the pros and cons of each approach and getting all the experts in the team to feedback into it. Just acting as a shepherd really as well as sharing my views too.

The great thing about written words is that they don’t lie. You can’t forget about them as easily and they have to be easy to understand by everyone who reads the document.

But I also sent a message to Marc asking him if he would advise me on how to go about all this and to see if he thought the document was a good idea and what other things I should do to get the right decision made quickly.

Marc agreed to meet me and his experience and advice was invaluable to me. He gave me tips on how to think about the problem so that I could approach it in a way that reduces conflict and how to help the team feel like they own the problem collectively.

Even though the tips may sound obvious it takes effort to put them into practice—at least for me.

The document is still being worked on but we have a plan on how to move forwards which I’ll update again on my weeknotes as and when.

Good reception for my new CSS-Tricks article on semantic HTML and ARIA

My article, on semantic HTML and ARIA has had a good reception I think. I’m particularly chuffed with some of the feedback that shows it’s really easy to read and understand for everyone:

I feel like this made something I don’t know about and don’t do, much easier to understand 👏🏻 Plus making websites more accessible = good, so it’s worth the read…—Charlotte Moore

Again, this is hugely down to Amy Hupe, who inspired me and helped me write an article with inclusivity in mind from the outset. I’m going to try very hard to write this way from now on.

Making things open made my approach to prototype versioning better

Last week, I wrote about automatically prefixing the version path in my prototypes. Graham Veal saw it and sent me a message with how to make it better:

Router before and after

// Old
router.use('/:path/', function (req, res, next) {
  res.locals.config = { path: `/${req.params.path}` };
  next();
});

// New
router.use('/:version/', function (req, res, next) {
  const version = `/${req.params.version}`;
  res.locals.getUrl = function(url) {
    return version+url;
  };
  next();
});

Template before and after

<!-- Before -->
<a href="{{config.path}}/details">

<!-- After -->
<a href="{{getUrl('/details')}}">

This is better because:

  1. Using a function means I only have to update the code in one place. It also simplifies the code within the template because concatenation happens within the function—not the template.
  2. The variable and function name are more readable. “getUrl” and “version” are easier to understand than “config.path” and “path”.

Even in this small way, this is nice reminder of the important of government design principle 10, make things open makes things better.

Pair writing on graceful degradation

Amy, who’s helped me write my last 3 articles recently suggested we pair write my next article. I’m really excited to learn how to do this, especially with Amy’s help.

We started last week on an article about graceful degradation and progressive enhancement. I’m writing the article because I think there’s some confusion about the practical difference between the two terms.

We started off with Amy asking me some questions to find out why I’m writing it and why it would be helpful to people. Then we discussed the structure and proposed an outline for the article.

After a break, we got started with the introduction. I must say it was really fun but also really hard for me. I usually write in one of two ways. One way is I just write and it comes out pretty well sort of first time.

Another way, is that I’m quite haphazard and I just start throwing bits down on paper and flesh them out in somewhat random order. Then I might rejig and rewrite a number of times.

But with Amy’s help she made us focus on getting the introduction right which while painful, really helped me define for my readers what I’m going to talk about and why.

It’s not perfect, and it might change as we write the body of the article. But it’s a really good start and the pain was worth the reward I think.

Links