How to write a UI Developer handbook
Where I currently work, the UI team had no formal documentation. There was no list of tools, guidelines or resources to be found in a single place. We had scattered link shares across Slack, doomed to scroll out of view and never looked at again.
Eventually I found our UI handbook, a few files in an out of date folder of a larger development team repository. It hadn’t been touched for years, so I set out to update our UI folder to something more useable for the team.
Creating your UI Handbook
Here I will describe the structure of our new handbook, which is in no way an exhaustive list, but can be used as an outline to create your own. Each section has been set up as its own markdown file in a modular way to make it easier to update certain sections. The handbook is not just a guide, but a collaboration, so making it easy for UI team members to update will help to improve it over time.
UI Developer onboarding
What happens when new hires join? Wouldn’t it be great to have a list of tools you work with so they can download and install them to get started? Who manages what project on the UI team? having a list of project owners will help newcomers reach out to those with the deepest knowledge on specific projects.
Fairly self explanatory, how does your team work with git/Github. Here you can talk about branching strategy, how to deploy your changes to a staging environment for review and any other steps in your process.
Beginning a Project
How would a developer at the company start their first project?
Personally, I like to review the designs and take stock of every component that’s going to be used. Seeing which ones can be combined and differentiated by variables, and at this point, coming up with names for them.
If there’s a preferred, or suggested way for getting started with your way of working or toolset, include them here.
Naming things can be hard, but it doesn’t have to be. I decided to include this section with common, and some uncommon, component names to get someone started when they’re stuck for a name.
A couple of links to a Thesaurus and some inspirational styleguides might help prompt some good naming.
Coding standards including file naming conventions and language specific standards.
What compression do you use? What formats do you use?
What are some key points to remember for performance? Is image compression required when uploading images, or do you have tools that do this automatically?
Accessibility / A11y
Let your team know what you expect from them regarding the accessibility of your websites or apps.. For most developers, accessibility is usually an afterthought due to time or budget constraints so lay out the bare minimum expectation of making your code accessible. If you’re one of the lucky ones who has the opportunity to develop something very accessible, add as much as you like.
Some useful resource links might include browser extensions or simulators to test for accessibility issues.
As we learn and develop our understanding of these tools, laying out our ideal folder structure or component naming system will keep things consistent across projects, ensuring someone will be able to pick it up fairly quickly.
There are plenty of great reference styleguide out there. Perhaps a couple of links to ones you aspire to would be a good start to get people excited about visual documentation.
Email builds these days are few and far between, but it’s useful to have an email guide for the odd marketing email.
Testing & Support
What, when, where and how should a developer test their code?
It would be useful to mention which tools you have available to test with. Do you have real devices or rely on a simulator service such as Browser Stack or Cross Browser testing.
Go Live Checklist
What happens before you submit your work to go live? It’s good to have a short checklist to make sure you’ve given it that last once over. Have you removed all your console logs? Are any remaining comments useful? Did you comment out a function and forget to delete it? These questions should improve your finally submitted code.
Keeping track of resources
Each of the above topics in the UI Handbook has a section at the bottom to link useful resources.
Aim not to fill this with everything you can find, but the top 5 or 6 relevant to the current topc will suffice without overwhelming the reader.
Review your handbook
Now your handbook has been put together get it reviewed, but not by your team lead. The content and language used should focus on newcomers, as it is those this handbook will help the most. Always ask newcomers if there was anything they felt was missing from the handbook in their first few weeks. Also keep an eye out for the sort of questions new hires ask and include those too. How about adding a FAQs section? Now there’s an idea I didn’t think of...