Design and Build

The majority of the project is the Design and Build phase. This is when we will actually build the thing we are building with the collaborator. Whereas Groundwork was the realm of research, this is the realm of building.

We say this phase is Design and Build because we are trying to avoid handoffs and running projects in a waterfall like manner. We want to emphasise a fluid collaboration between design and development. We should try to start and finish this phase together.

In reality, because there is often some element of feedback needed on visual design then there is necessarily a workflow that runs: visual design → sign off → build. This is especially the case when building websites that are primarily about displaying content. We are trying to dissolve this as much as we are able, however.

Thing on the internet

Normally the designer will have to begin designing something before the software engineer has something to build. They might have an impression from the Groundwork phase, so they can get moving on that. For example, setting up basic fonts and colours.

Before all of this, if the project involves something online, it is is crucial to get it online. You want something deployed on the live internet. We call this internally "thing on the internet". Everyone must celebrate this boldly when it is done! 🎉

Preferably this thing will have a proper DNS address for the collaborators site - e.g. at something.collaborator.org. This flushes out any difficulties setting their DNS routing up as early as possible.

We should deploy this with continuous deployment wherever possible. Projects where we don't use continuous deployment we tend to regret not doing it. In fast moving campaign environments we've discovered continuous deployment is not a nice to have, but often operationally crucial.

Thing on the internet also brings an early sense of confidence to the project. So should be actively shared with the collaborator if it is stable.

Wireframing

Before moving to visual designs, we will:

• Identify user groups and their needs
• Map out user flows through the site
• Make an overview of the current and planned content structure
• Make a sitemap
• Make a map of how the organisations different technical systems are connected (e.g. membership, donations, internal admin, automations)
• Make low fidelity wireframes of each page template
• Make low fidelity prototypes to explore interaction paradigms

The idea is that these lower fidelity, "birds eye view" designs show the content structure, architecture and user flows of the site or tool. We then make high fidelity visual designs and a design system that shows the visual look and feel of the site or tool.

The goal of taking this two-pronged approach is to be able to focus on UX and content with many low fidelity designs that are easy to create and iterate upon, then combining these with less but higher fidelity designs that reassure our collaborators that the visual style and interactive feel of the site match their expectations.

Building out and signing off visual designs

After wireframing, visual design begins. Whereas in the previous phase design has limited itself to elements, branding and prototyping, we want to be able to show the collaborator something visual. However, we want to give the collaborator as much as an impression as possible of how things will look, without building out all the screens and pages in Figma.

Spending too long in Figma is wasteful. At the end of the day, the collaborator is looking for something on the live internet, rendered in a browser with HTML, CSS and JavaScript (or in a mobile phone application). HTML has a different "mouth feel" than Figma, and the gap between the two mediums can be the source of minor disappointments for collaborators. Having multiple rounds of collaborators looking at Figma, suggesting adjustments we then make and then looking at Figma again is a certain way to chew up time and budgets and make the project lose pace. Building out all the pages makes Figma unwieldy to use. Making the surface area of the project so large in design makes it difficult for the designer to keep in their head, which is stressful and leads to slower progress. We want to show the collaborator a few key pages and workflows and then component designs that are the building blocks for the rest of the pages or screens that will enable the rest to be built out.

This is a really delicate thing to navigate, as people who aren't used to digital projects often expect to "sign off" how each individual page will look. Not "seeing" a specific type of page might cause some anxiety in the collaborator, who might think that we've just forgotten about it, which makes the collaborator not feel heard and damages trust. We are instead trying not to waste time and budget building a nice picture of a web page, when time could be put towards building that web page for real, with real content, that is dynamic. The flow from Figma to a live page is able to be quite rapid, especially with modern tools like Webflow, but we want to avoid too much time "stuck in Figma". The best way out of this dilemma is to explain why we are approaching it this way and attempt to get the consent of the collaborator to proceed with building, without them signing off every page or screen. However, in situations where there is a large organisation, with a complex hierarchy of people who need to have a say, this might not cut it. While we can do additional narration, or train people as to why in digital projects people take a style-guide based approach, at some point someone might have to grind out all the pages and screens. We want to avoid this however, so the collaborator should be informed of this trade off (we will have less time to build and improve the real thing) and go into whatever decision they make with open eyes.

Despite all these caveats, usually we are able to present a limited sub-set of pages or screens, sufficient for the software engineer to get going and for further tweaks and improvements to occur within HTML or CSS (or in a phone app). It's best to try and get a formal email from the collaborator that this is signed off. A formality, but marks an important point in the project, so is worthwhile.

Collaboration between design and software engineering

The relationship between designer and software engineer is a really important one. So we are going to give an impression of how it should work in the Design and Build phase.

Ideally, the software engineers involved in the project should see the designs before they are shown to the collaborator, preferably at each stage, for example from prototyping to full visual design. While designers make efforts to not build out pages or screens that would be really tricky to make given the general capabilities of web browsers and the specific capabilities of the software stack involved, designers aren't going to get this 100%. So there needs to be open discussion of things that would be easy or very hard and time consuming in a way that doesn't actually improve functionality. We don't want to show the collaborator something that will look or work drastically differently from what we show them in the designs. This can cause disappointment if it is so complex, we can't actually make it. So up front have a conversation between the designer and engineer about what is possible. Better to take it out of designs, than leave something in that isn't going to be built within the project scope. This conversation also enables a lot of intended functionality to be cleaned up that is not evident from static designs. For example, "when I click on this, what happens". Or "are these filters intended to be additive or independent". Any decisions about how things function should be noted down either in Figma itself or recorded on Linear. We don't really want to have to have this conversation again, as it is frustrating to have to keep explaining, or worse, have to say something isn't what you envisioned when it is in code. Though we aspire to keep the same software engineers on a project, sometimes it doesn't work out, so recording how something should work is important.

As a cooperative we are known for our flair with design, so it is really important that when a designer has done a particular piece of cool flex, we try as hard as possible to do it as software engineers. We are deliberately creating things that are beautiful, because people who are involved in bringing about a better world deserve things that are beautiful. While we don't aspire to the pixel perfect translations between Figma and live pages or screens, we do aspire as software engineers to respect the work that has gone into the designs and not just interpret them in a way that simply conforms to whatever is easiest to build out. This said, we also don't want to make this a one way movement, where the designer is creative and the software engineer just builds out the the visuals and interactions, dictated by the designer. Both designers and developers should be able to bring their creativity to a project. Ideally this is going to be a collaboration, with the designer and software engineer bouncing ideas off each other. This will result in a stronger outcome. What it might look like is something like this: "I think it would be cool if we could do it like this", "actually, did you know that browsers can now do Y, which works really well and is very easy". The same goes for features themselves, not just the way they will look. This joyful back and forth should continue when the designs make it into code.

This is a work in progress. We work together in an atmosphere of collaboration, cooperation, solidarity and respect for the different disciplines across the cooperative. Any tensions in this relationship should be talked to openly and continuously improved.

If there is a particularly cool piece of functionality that the designer and software engineer have established will be time consuming, but is really excellent and might potentially move the dial on the political goals of the project as a whole, it should be the decision of the collaborator to make this trade off. Collaborators could sit in on these conversations around what is possible if they like, as it will certainly improve their understanding of the project. However they are busy people and the digital element of their work is only one aspect of what they are doing. The invitation should be there, but the expectation should be that this is a conversation we have internally. Conversations that really get into the reeds of technical questions can also be very overwhelming for people, or boring.

It is important to note in this that one of our values is pragmatism. While we value good design, we also take into account the political and material reality of the projects we're working on. There usually isn't time to do lots of self-indulgent design iterations or complex interactions (unless our collaborator has asked for this). In our opinion, digital projects like this are also not as usable, fast or accessible for the people using them. We always aim to create something "beautiful and useful", as William Morris would say.

Tackle the most technically risky thing first

When it comes to the technical aspects of project, try and tackle the most complex or technically risky thing first. The collaborator is unlikely to prioritise this themselves, but we need to be quite firm on this and emphasise that not doing this puts the project under risk. While we should have tried as much as possible to soften technically risky elements of a project in the Groundwork phase, by doing good research and prototyping, sometimes you are only going to know by actually doing the whole thing. For example, when there is tons of data involved and edge cases or difficulties will only come up once you've dug into it. You can do further spikes) to try and further soften things, but at some point you are going to have to just confront the complexity. We should try and break it down into more simple constitutive parts and so on, or avoid doing something technically complex if it not really going to move forward on the political goals of the project, but sometimes we are just going to have to do it! We are here to tackle hard problems when the movement needs to work with technology, so need to meet that challenge.

Common technical risks are:

• Migrations
• Translations
• Monetary transactions
• Integrations
• Anything involving a large quantity of anything - apart from anything else, with a large amount of anything, processes take longer and therefore feedback loops are far slower

We try and anticipate these risks in Groundwork, but sometimes you can only see the real problems by doing it for real, sadly.

For collaborators, this bit can be a bit alienating. Our team goes off, sometimes for a long time, tackling some thing that they can't see until its done, and the only thing the team is saying to them is "there is something really complex going on over here the tech wizards are up to". As we approach projects as a collaboration, we hope to instil in collaborators respect for the craft of software engineering to the extent that if we are spending a long time up to something, it is for the best for the project, because we really really care about the goals of the project and don't do things that are wasteful or aren't in there to meet the goals of the project, ultimately in terms of social change. However, keep in mind how this might all look. It looks to the collaborator like things aren't moving forward and the project is stalled. It looks like we've stopped.

To avoid this worry from the collaborator, it is best to over communicate progress as you are getting on with it on Linear. Better a stream of pretty boring updates on Linear about problems encountered along the way, they can tune out of, than a communication void into which collaborators read inactivity or worse, not really caring about the work being done. A short update is much better than the collaborator getting anxious.

Keeping the collaborator in the loop

Throughout the design and build process, we want to keep the collaborator in the loop. Primarily we will communicate with them through Linear. At a point where there is something for them to see, we can alert them there and then get them to move the issue to done. We can also use Updates in Linear to report progress. We should remember these are very familiar tools to us, but often new tools for the collaborator and be sensitive to this.

At the end of every Cycle in Common Knowledge, it is nice to send the collaborator a quick email explaining what has been done. The Project Steward should be responsible for this. We can also arrange regular meetings to check in on progress. A communications void is really a bad situation, so we want to be as pro-active and over-communicative as possible. This is especially true if we are encountering difficulties in any way. We want to be honest, clear and explain what is happening to collaborators. The ball should always be "in their court" when it comes to communication back and forths. We should be waiting for communication from them, not them waiting for communication from us. Even if the situation is no progress we should communicate this: "we've not made much progress as this other major political event has happened and we are tight on resources handling this".

In general email is best for meta-comments on progress, staffing or discussions of budget, where a bit more formality is in order. Day to day feature conversation should occur on Linear and occasionally real time chat where we are using it, but anything substantial should end up on Linear.

Sometimes, because they have busy lives or because they lack the confidence with the tools, collaborators don't look at them. In these cases, it can be kind to provide them with a short summary of what is going on, linking back to Linear. This seems to be especially the case with Productive, where time and budget are tracked and the tool is a little harder to get into and use. Unfortunately, financial limitations on projects are a thing and it is important to deliver projects on budget. Drawing attention to the current position of the budget regularly is really important. Best if people check it themselves in Productive, but if this seems not to be happening, summarise the position of the budget and link back to Productive a regular intervals. A least once a Cycle. No one wants any surprises that the budget is running out but there is too much to do.

The collaborator needs to see something

One difficulty with projects is that until the collaborator can see something live on the internet, we are so far just having a discussion. We are moving Linear issues about and talking about things, but there is going to be a lot of worry that the thing may or may not get done. For this reason, it is important to show progress early. Perhaps a complete page or screen.

While it is important to show progress, it is also important not to show something half finished that is only going to increase the collaborators worry by something being handed over and feeling broken. This damages the collaborator's confidence in our ability to build things and trust, which is very difficult to regain once it is lost. For people who don't have a lot of experience in digital projects, all things are just plain broken, and no amount of saying "this is easy to fix" really reassures after that initial hit in confidence. Ideally what we want is something complete, but a small slice of functionality that demonstrates clearly to the collaborator "now we are really moving".

QA as you go along

When in Design and Build, mostly the designer is going to be taking quality assurance (QA) responsibilities to ensure what is being built has been built in the way it has been envisioned. We should try and do this on an issue by issue basis, as things are built, rather than handing over to the designer a huge lump of issues to look at, as we move into Improve and Launch. We have done this, but it is something we really want to avoid: it is no fun.

Even though the designer is going to be doing QA, the software engineer should take responsibility for testing their own work before handing it over. We want to avoid a quite draining back and forth, where the designer has to hand the work back multiple times for tweaks.

So the software engineer should take a look over their work and think:

• Does it look basically like what I can see in Figma?
• In terms of the detail in Figma, are the important details (padding, margins, spacing) accurate or - if there was some reason why this wasn't possible - at least consistent?
• Does it function as we agreed it was intended to function?
• Has implementing this issue caused anything else to break? In the ideal situation, we'd have automated tests to verify this, but if we don't, it is our responsibility to verify this.

The questions in the pull request template are intended to prompt this reflection.

In order for the designer to QA things it needs to be somewhere they can see on the internet. Ideally we want a feature branch based deployment, that isolates the feature on its own environment for testing. We should try and get to a position where this is possible with all our projects, because the pace and quality it permits is disproportionate to the complexity of setting things up initially.

Discussion should happen on Linear and corrections should be made when they are needed. Once everything is good, we can merge the code in and move the work for the collaborator to take a look at then move to Done. We want to avoid giving something to the collaborator that doesn't work so well. As above, this damages confidence and trust.

If the designer is unavailable, the Project Steward will be QA of the last resort.

Pull requests

In Groundwork we were probably playing fast and loose with experimentation with code, or doing a lot of set up where it is too boilerplate for software engineers to make pull requests. However, now we are really building things, we want a certain level of code quality, so we are going to make pull requests to another software engineer within Common Knowledge to review code.

Discussions around the code should go on GitHub on the pull request. But occasionally a bit of signalling back and forth can occur on Linear. Code can be reviewed simultaneous to designers checking it out. Code reviewers should try to check the basic functionality as well as purely the way the code is. In the pull request template, there is a section which describes how to test the issue. As the person handing the code over to be reviewed, you need to make sure this is filled out.

In terms of who is reviewing the code, in the first instance it should be another software engineer working with you on the project. If none is available, and sometimes just for fun to keep people in the loop, it can be another software engineer in the cooperative.

For the reviewer, please do try and get code reviews done quickly. You are holding everything up if you don't get them done. We want to maintain good quality code, but we also want to act in solidarity and pursue the aims of the project, not simply nitpicking. So approach review with this approach.

In the last resort, one can merge one's own code. Sometimes timelines mean we might have to. We want to go into this with our heads screwed on when this does occur.

Adding content

At some point, the collaborator will need to write, edit and add in their content. For a content based website, this means logging into the CMS and adding this in. For a more tool-like project, this means writing the copy that is seen on screen, including instructions and framing information and making any translations needed.

In campaigns, things are very fast moving, and political sign off sometime requires extremely last minute changes to wording. We like to allow collaborators to make changes to the content or even copy in a tool themselves for this reason. We also want this not to be a task that needs engineers to do. Organisers should be able to make changes on the fly as suits their goals and the days to day demands of their tactics.

In this section, we use CMS generically from now on, but we just mean the system for managing content, which might not be a formal CMS system like Wagtail or WordPress.

In the past, we've tried onboarding people to the CMS right at the beginning, before the front-end has been built out. However, this doesn't always work amazingly well because it's hard to add content without knowing what it looks like. There is a chicken and egg problem.

Therefore, there is usually a point at the end of Design and Build where we onboard collaborators to the CMS and do a few training sessions. They can start uploading content while we do detailed QA. This is an important step, because often lots of new bugs pop up only when the real content is added.

As in the Kick-off Meeting it is worth emphasising that people often underestimate how much work there is in creating and uploading content for an entire website is - we do it ourselves with our own website! Collaborators need at least one person to steward the project within their organisation, and ideally multiple people to enter content. Collaborators should work on creating and collecting content while we work on the Design and Build phase.

Consider doing earlier feedback

For very long projects, we can go for a long time without opportunities for feedback and improvement via a retrospective. While we have Cycle retrospectives, sometimes it can be useful to have a retrospective at an appropriate point to try and improve, or simply to demonstrate and celebrate progress so far.

In the typical project phases, after Design and Build comes Improve and Launch.