some advice on hacks posts
Christopher Blizzard
more distributed I might offer up some (free!) advice on some of the
things that I've seen that I probably would have fixed had I been part
of the review process, and the kinds of things that I usually look for
when I'm doing a post. Some of this is going to sound overly-critical,
but it's not. It's just what I've seen that I've learned helps build
better posts. I'm hoping that everyone will use it as a style guide and
how to think about doing posts for their own stuff in the future as well.
1. The little lead-in is meta information and should be italicized.
This is to indicate that it's coming from us, not the author, which are
often different people. Also please make sure you double check the
spelling of people's names and that you link back to their blogs if they
have them. Google Juice is part of the power that we have - we should
hand it out whenever we can. :) Also, seriously, where here to
celebrate the works of others. They are the ones doing the cool work,
not us.
2. Make sure that you use the <pre lang="javascript"> etc - it does make
nice highlighting. Also make sure that the code lines up inside of the
500px limit - this isn't always possible, but it's possible to split up
long lines, eliminate code that doesn't need to be in an example or
otherwise make it more pleasant. I've done this a number of times.
3. Make sure that images line up inside of the 500px limit. I've seen
some where we're overlapping past that limit.
4. Watch out for wordpress eating tags. It will do so if you're not
careful.
5. Link to live demos if you can. They aren't always available but when
they are it's good because then people can read + steal code.
6. Link to docs in developer.mozilla.org if you can - we're trying to
make sure that people use the site since it's (often) one of the best
docs for a particular function available on the web. Plus some really
helpful guy has been adding information about compatibility to most of
the features we link to. (Thanks to whoever you are!) Also
developer.mozilla.org is _really_ good compared to other sites and we
should be using it as a centerpiece.
7. Posts that are part of the 35 days project should be included in the
35 days category. Posts that are features should be in the Feature
category and demo in Demos.
8. Make sure that you go and update the 35 days wiki page when you're
done - we use that to measure when we're done and what we've already
linked to.
9. Please make sure that you post to the @mozhacks twitter account when
you post. During the middle of the day is best - that's when most
people are likely to re-post and follow those links. Also for 35 days
I've been using a bit.ly link that actually self-describes it.
35something is a link that other people are more likely to follow if
they are looking for info on "something".
10. Titles. Titles are super-important. A good title is one that
describes exactly what you're about to talk about in no uncertain
terms. There's a good rule from journalism - don't bury the lead. What
that means is that the entire point of your article should be summed up
in the first paragraph of the post. In this case the title is even more
like that. Trying to be clever is good, but being obvious is about ten
times as important. I'm going to pick on you guys a little bit here
with a couple of examples - "video - more than just a tag" should
probably have been "the html5 video tag" for two reasons: 1. that's what
you're actually talking about (and it's a feature, not a demo) and 2.
the html5 name actually has juice, even though it's not even done. The
other one was "working smarter, not harder" which I edited to be "using
web workers: working smarter, not harder" because it gave no clue about
the content of the post. The other important thing about titles - it's
semantic information about the post and search engines use it. If the
title doesn't give search engines a clue about the content it's going to
have a lower ranking. So please keep this in mind for your own posts as
well.
11. The post slug. The slug is the little bit of information that makes
up the end of the url. This, just like titles, matters a ton. People
mouse over urls to get a sense of the content that someone has linked
to. Just like titles, search engines actually use the content of a url
as semantic information to set rankings. So please be conscious of this
when you're setting them. In the case of other posts, I've been even
more sparing with the slug than with the title - pick out the important
nouns and verbs and use them. Also this is important because once it's
up you really can't change it. To pick again on the web workers post,
the slug is 'working-smarter-not-harder' which honestly sounds like a
spam url, not a post about the latest in browser technology. Should
have just been 'web-workers.'
12. Don't be sarcastic or crap on other browsers explicitly. I've
edited out some over the top stuff from a few posts. We're here to
educate and lead, not to be snarky. That doesn't mean that we shouldn't
include technical information about deficiencies in other browsers, but
we should never be arrogant-sounding jerks. Ever. Like, ever, ever.
Even more important than not sounding like an arrogant jerk is to
actually not be an arrogant jerk. Just sayin'.
13. Remember that you're always always telling a story. Things should
flow from one topic to another easily where possible. Big breaks in
content or the end of a thought should be broken up by a bold title with
a new topic to help ease the reader from one topic to the next.
Sometimes I've seen posts jump around a little bit. Keep in mind that
the reader probably doesn't have all the same context that you do.
14. Code helps - always include code samples where you can, subject to
the rules above.
15. Avoid language that you would use in speaking or on a TV
commercial. (I am as guilty of this as anyone!) Watch out for extra
"for example"s and "Well," and "So," or "what you've been waiting for"
which we always say but often do not write. When I read stuff like this
I think of this video: http://www.youtube.com/watch?v=PPsUmhqncAg (which
you should watch because it's fucking funny.) If you re-read what you
wrote and in your head it sounds like Gabe and Max then rewrite it. And
see 17 below.
16. Some writing style from the old mozilla.org site. Read this:
http://www.mozilla.org/contribute/writing/guidelines#writing-style and
in particular this:
http://www.k-1.com/Orwell/site/work/essays/language.html (As jwz
originally said: Read it again. Have it tattooed on the inside of your
eyelids.) Really, it makes you a better writer who wants to get a
point across.
17. Oh, yeah, rewrite everything you write. Remove entire paragraphs.
Be brutal. If you wrote something and it's ten paragraphs odds are you
can say the same thing in two. Good writing is defined by what you are
able to say with the fewest words possible. This goes against the
feeling that what you wrote is good, but it's not. Certainly not the
first time. So don't get attached to your own words because you're
probably going to just have to delete them anyway. And if you don't, I
will. :)
Anyway, that's the stuff off the top of my head. Sorry if some of it
sounds brutal, but trust me - it makes for better content. Also watch
the Gabe and Max video again. It's funny.
--Chris