Charlotte Spencer is a front-end web developer with a keen interest in semantic HTML, progressive enhancement and accessibility. When they’re not programming; they are writing about the web and their experiences with it, reading, or preparing for the zombie apocalypse. They tweet at @charlotteis.
Important: The texts published by Charlotte Spencer on the Pastry Box Project are released under the following license:
This license overrides and takes precendence over the Pastry Box Project's default license.
Lowering the barriers
New York's hottest web framework is unicornThunderstorm.js. It has all the doodads you need to foo and bar your components with server-side tomfoolery. It's easy, just plug and play! Connect the flux capacitor to the spiderpug and you'll be abstracting over your synapses.
That's what I see when I read most READMEs for the first time. A lot of cool technical words mushed up into something to make people want to use your product. But, offers no real explanation about what it does.
Of course, we have to entice people to use our thing, I'm sure there must be more detail further in.
Just do 'sudo npm gulp rubygems' and you're ready to go!
This is a post about the walls we've built around our projects. Frolicking about in our bag of tricks, whilst others are trying to dig into our castle with a rubber teaspoon.
Here are some tips to make the process easier.
Documentation Driven Development
No functions, models or tools should exist without being documented. We often lose track of what we're doing, so I suggest writing your documentation first. Have a loose outline of what you want to achieve, so you can keep track of what you intended to do. Once you've written the code you can make any changes you need and flesh things out.
Many open source projects wont let you contribute code without having written tests first. I say the same should go for documentation. Documentation can become outdated so quickly, encouraging all contributors to keep documentation in mind from the outset will slow the ageing process greatly.
Language is the most difficult thing to get right. As someone writing documentation, you have to create something understandable to everyone.
By default, your writing should be understood by individuals with a 12-14 year reading level. There are tools you can use to help you with this such as Hemingway Editor, which I used to write this post.
Avoid use of "easy", "simple" and "just". If you tell me something is easy and I don't understand it, I feel alienated. What is easy to you is not easy to other people. Avoid phrases like "so easy your gran could do it". My nan has no interest in using your Rails plugin. Nor, does she appreciate the implication that you simplified things especially for her.
Demos, Demos, Demos
You need demos. Anything from small snippets for your API methods, to full blown tutorials.
Have different demos to offer different contexts of use. As humans we struggle to grasp how to use something if we're not shown how to do the thing we want to do exactly. A few different tutorials gives variety and invites more people in.
If you can, have your demonstrations use different mediums. Whilst one person can get all the information you need through reading, another wont be able to grasp the concept until they've seen a video. Naturally, all videos and audio content should have subtitles/transcripts.
Be active in the community
Make yourself available to answer questions. I work with several open source communities and each have open Slack/IRC channels. One has a bot in their chat that alerts them to new Stack Overflow questions related to their framework. One has regular office hours every day and a dedicated FAQ application. All are active on Twitter and dedicate time to answering GitHub Issues.
My suggestions can be expensive in time, money and energy. When you're building something for the first time, all of this comes down to you. Focus on the documentation in the beginning. By doing that, you'll create a welcoming place for others and then they can start helping you with the rest of it.
It's okay if you don't get it right the first time. It's never going to be possible to have everyone understand your project right away; but at least replace my spoon with a shovel.
You don't need a degree
When I was 17, I was applying for University places. I don't remember deciding to do this, I did it because everyone else was doing it, because we were told that to get a good job, we needed one. At 18, I started a degree in Psychology, I was going to be a clinical therapist. Three years later and I was exhausted, so decided to take a year out to do something different before going back to get my Masters.
That never happened. I worked for two years and by 2014 I had no idea what I wanted to do, but it wasn't that. So, I started to teach myself web development. One epic montage of hitting a computer in my pyjamas and this year I accepted a full-time position as a "software engineer".
Before I got that job, I doubted my abilities. I wanted to give up because there was no way anyone would hire me without a "degree in computer science or related field". I held off applying for any job for a long time because even the internships wanted qualifications I didn't have.
It took me a long time to realise that in the web and many other professions, a degree is not necessary. As a person in web, you need to show that you have the knowledge and the skill to build things. That does not need a degree.
Why do many job applications list a degree as a need? I did some intensive research (wrote a tweet) and people wrote back to say that it gets rid of the people who aren't serious about the job. Others said it was a "nice to have" rather than a strict rule.
To both of those points I say: take it off of your job spec. You can't measure "seriousness" about the role someone is applying for by whether they have a degree. It's nonsensical. Would you choose the person with a degree who sees this as just another job, rather than a self-taught new starter who has enthusiasm leaking out of their eyeballs?
Having a degree as a "nice to have" on your job spec might seem better, but it's better to get rid of it. When looking for internships, I ended up avoiding any job that mentioned a degree. If I'm up against someone who is just as good, but they have that 'nice to have' degree, are they going to get it over me? I know I work hard, I know I'd be right for the job, but could a piece of paper cost me that opportunity?
I'd encourage any employer to remove qualifications from job specifications, unless you're hiring an actual rocket scientist. By opening your eyes to the amazing amount of talented people out there, you're going to be much better off.
I have worked with quite a few people in a few short months. Some had CS degrees, some didn't. There was no difference in 'skill' that was caused by a lack of a degree. We all push numbers and letters around until they make sense.
I sit at my desk every day and talk sternly to a computer to make it do things. You can do that too with practice. Go get a degree if you want one, but you don't and shouldn't need one for other people to see you as hireable.
You have a website. It looks good. You love it. Your friends love it. Your cat thinks its "just okay" but they're a cat, they don't care about the web.
But, it's completely inaccessible. The heavy page weight caused by all your funky animations mean it takes long to load on a mobile device. Your potential employer whose vision is poor can't make out the contrast between your background and your body text to read your CV. And myself; whose hands occasionally don't work well, can't navigate through your content using my wicked cool keyboard skills.
It can be overwhelming when you realise that a large percentage of the population may have a stressful experience with something you have built. You want to make it better but your line manager says its not the priority. Your client just doesn't have the budget and even if they did, you don't know where to start.
The first thing to realise is that it doesn't have to be done all at the same time. In fact, throwing a bunch of ARIA roles at your markup without thought may hurt rather than help.
Do it incrementally. Right now, you're inaccessible. Tomorrow, your images might have descriptive alt text. Next week, your design might have an improved contrast ratio. Next month your header navigation might have a more usable structure, with better headings and links with active and hover styles. With each iteration, more and more people could have an effortless experience each day.
Getting started with accessibility
Use your website with a screen reader
- How is your content structured? Make sure each block of content has a descriptive header.
- Do you have to wade through 27 navigational items before you get to the main content? Include a "skip to main content" link!
Accessibility compliance checkers
- Do all your images have their appropriate alt tags, so someone can still understand what the image you've included is, even if they cant see it?
- Do your form inputs have a label linked to it so I can tell which box takes my username and which takes my password?
Convince your boss
When it comes to accessibility, some people need a business case. This is not something this post will cover. The most I can say is that an accessible website means more people can have a positive experience with your website which can in turn lead to increased revenue.
Even if you do have the go ahead, where do you start in the code base? When I start working on a project that is already well into its existence, I set a rule of "if I touch the code, I can make it better". If you're adding things to your navigation, now is a good time to make it accessible. If you haven't been given the go ahead to start working on accessibility, this is an excellent way to sneak it in.
No self-professed accessibility expert drank from a golden chalice and knew everything they needed to about accessibility. Like anything, these things take time.
Something I like to do is rate the experience I have on each new website I visit. Can I use it on my phone? How long did it take me to get the information I need? Is the content clearly labelled, is it easy to understand? You need to learn to train your brain to think about things from a different perspective.
By implementing carefully considered accessibility bit-by-bit, over time it will become second nature. Even better, you'll be able to build websites and applications from the ground up with an accessibility first approach. It's much easier to build something right from the beginning, instead of shoe-horning it in halfway through the process.
With each step, you'll be helping to make the web what it should be: accessible for everyone.