Webmaker/How To Write Projects
How to write up a Mozilla Webmaker project
1) Try to start your project title with a *verb*
Like "Make, Create, Hack, Play, Remix, Design, etc." This is important for consistency across projects. And also because it reinforces the central theme: this is a place to make cool stuff with the web.
2) Try to sum up the entire project in one sentence off the top
The first sentence. Then boldface it, as a nutshell right at the top.
The project *title*'s main job is to make you want to click. It should be clear, but a little poetry or mystery is ok too. The first sentence's job is different -- it should clearly spell out *exactly* what the heck this is, as plainly and clearly as possible.
What do you do, make or learn in this project? What does the actual experience consist of? Give it straight, with no poetry or fancy dressing. If it's a project about fixing broken HTML tags, you don't have to say it in the title -- but you should say it in the first sentence.
3) Don't make it look or sound like it's "for kids."
If you do, you may end up turning off the very kids you're trying to attract -- *and* turn off adult novices who may have otherwise been interested as well.
We need to thread a very particular needle with many of our projects: ensuring that they're "youth friendly" but -- at the same time -- suitable for adults as well.
The good news here is: even *kids* often don't want to do something that sounds like it's "just for kids." So by making sure our language and tone are right for adults, we may actually be making it more attractive to youth as well.
Our test should be: does this sound like something *I* would want to make or do? What would my friends or peers think of this? If it sounds dumbed-down or baby-ish to an adult, it probably will for kids as well. And tweens have a hyper-sensitive radar for anything that seems remotely juvenile.
4) Avoid jargon and inside jokes.
Including insider / webby jokes like "o hai!" or "Ryan Gosling hey girl", etc. These often have a nice friendly and casual air that shows we speak the language of the web. BUT, a lot of people just don't understand these references. And they don't localize well at all. So let's try not to use them.
We don't have to be overly rigid with this. Part of Mozilla's voice is a bit of whimsy and a punch on the shoulder. We just need to exercise restraint and be conscious of localization.
5) Definite technical terms
And link to supporting definitions. Be aware that many people won't know what "CSS" or "Javascript" means. You don't have to define *everything*. Just try to provide some quick context, and link to a supporting defin
6) Use words that work (whatever they may be)
Use whatever words you think are best to get the point across in the fastest, easiest way for everyday people. There are no hard and fast rules. Break conventions that you think are limiting. All that matters is whether the intended audience gets it.
This is important because experts and insiders (particularly in technology and educational circles) tend to really over-rotate on semantics. Wording issues that these experts insist are vitally important often don't matter to regular people. Break those rules. And test with real people and target audiences, not just colleagues.
7) Put a huge emphasis on the finished product. What are you going to *make*?
What's cool is the finished product. Start from the finished product and work backwards. What -- in the most concrete possible terms -- do you come away with when you're done? Why is that cool? Start there.
8) Err on the side of clarity over style
One of the things you notice about sites like Lifehacker or Make Projects is that the writing lets the finished product speak for itself. It's very decidedly *not* Gawker, for example, where the writing is always very inventive, stylish and internet culture savvy.
But for maker sites, it doesn't have to be. If you're making a coffee table out of Rubics cubes, or your own electric guitar, or a marshmallow machine gun, you don't need to dress up the instructional copy in fancy verbage. You just need to trust that the finished product is cool, describe it well enough to show why, and then be as *clear* as possible in how to do it -- and then just get out of the way. We need to aspire to that as well.
e.g., good: "Tweak your Tumbler blog using these simple HTML and CSS tricks."
bad: "Conquer the blogosphere with your stylish musings"
good: "Write the next chaper of this interactive novel."
bad: "Create multimedia mayhem"
9) Test it on yourself: "does this sound like something *I* would want to do?"
Before you send it out of the kitchen, taste it yourself. If you don't honestly like it, others probably won't either. See Rule 3.
10) "Skills vs. topics"
"Skills" are webmaking skills. e.g., HTML, CSS, Javascript. Topics are interest-driven. e.g., hip hop, fashion, dinosaurs, music.
