Link-friendly content

Have you published a blog post or a GitHub project? This document gives tips for making your content appealing to link to. They are based on things I noticed while collecting material for the JavaScript Weekly email newsletter. The tips should also make your content more appealing to “normal” readers.

Cosmetic tips

A few superficial measures for a better first impression:

• Spelling: Make sure your spelling is OK. Alas, the “.js” suffix is used in many variations. When in doubt, look up the name you are referring to. Names that are very often spelled wrong:
  • JavaScript (not Javascript)
  • Ajax (not AJAX): it’s not a real acronym, see the post where the term was invented
  • Node.js or Node (not NodeJS): this one is more tricky, as there are many variations. Starting with a capital N and ending with “.js” seems the most common way to spell it.
• Links: Don’t use URL shorteners. They don’t let you see where they are pointing, undoing the self-descriptiveness of good URLs (see below); they stop working if the shortening server is down; and they are both easier to break (e.g. by losing one character) and much harder to fix.

  On Twitter, not using a shortener means using Twitter’s built-in t.co service for which the original URL is stored with each tweet. Observe which tweets use t.co (you can see the original URL in the tweet) and which don’t – the former group is more informative. Alas, Twitter doesn’t give you access to the statistics collected by its t.co server. They really should.

• Typography: Not a big deal, but you can pay attention to the following typographical details.
  • Curly quotes: “hello” (not: "hello")
  • Curly apostrophes: it’s (not: it's)
  • Proper dashes: nice – I like it (not: nice - I like it): Double hyphens (--) are often used as a work-around, but with widespread Unicode support, there is no need to do so these days.

Tips for blog posts

• Let us know who you are. I’ve come across pages where it was virtually impossible to find out who had written them. Demo pages are especially notorious. Thus: Let us know who the author is, how they can be contacted and what the current page is about.
• Use descriptive and stable URLs. Creating nice URLs is an art form. If you succeed, people will look at your URL and immediately have a rough idea what it points to. Useful elements:
  • Year of publication and month of publication. This automatically dates your content and gives important context.
  • Stable file name. You will often change your mind with regard to the title of a post. The file name should be something that you are absolutely sure about, as it can’t be changed later on.
  An example: https://2ality.com/2013/02/asm-js.html
• Date your post. There should be a clearly visible date of publication. This is necessary, but has the disadvantage of making content seem dated that is still current [1].
• Descriptive page titles. You should be obsessing over this one. This is what people tweet, it has to both describe what the page is about and make people curious (hopefully, those are not mutually exclusive goals).
• Start with an abstract. The beginning of a post is what people read after the headline has reeled them in. They have to decide whether the content is really for them. Thus, give a brief summary, let people know what to expect. You can also mention what is unique about a post, what makes it stand apart from the crowd. Good abstracts are used as link descriptions by many link blogs and email newsletters.
• Avoid long code snippets. Excerpt and link to the complete code elsewhere (e.g. on GitHub). If you feel that people have to see all of the code then break it up into smaller pieces.
• Series of posts need a main page. Have a clear starting destination that includes a table of contents. Make sure that that starting destination is easy to reach from each part of the series. It is what people will often link to.
• Don’t use Google+ for blogging. This tip is probably controversial, because it is subjective: Google+ is very convenient for blogging and much good content is published on it. However, I dislike it for four reasons: First, Google+ URLs are less pretty than typical blog URLs. Compare:

      https://plus.google.com/110516491705475800224/posts/58Cs7co928k
      https://2ality.com/2013/02/asm-js.html
  

  Second, Google+ pages are more heavyweight than blog pages, they put a strain on your browser. Third, blogs usually look better than Google+. Fourth, blog content is easier to navigate (archived by year and month, etc.). The last three points are unavoidable: Blogs can be optimized for blog content in a manner that Google+ can’t.

Tips for GitHub projects

GitHub project pages often function as the home page of your project. I like their predictable structure and quick overview of the project’s contents.

• Project details – description: Fill it out, it is the closest thing to a title that a project has.
• Project details – website: Is there more project-related content elsewhere? In addition to the description, you can also specify a website for a project. Decide: Do you really need a separate website? What is its relationship with the GitHub project page? Note that you can also host web pages on GitHub [2].
• Add a readme file to the repository. You can choose between several formats: plain text, HTML, Markdown, AsciiDoc. Such a readme is essentially a blog post introducing your project, thus all of the above tips for blogging apply. For a readme, the title is especially important, because, visually, it becomes the title of the project page. Additionally, the project’s “spec sheet” should be mentioned early: what are the requirements, what technologies is it based on, etc.

The dilemma of curating news

Curating online news is hard, especially in the domain of web development: the community continually publishes an abundance of good content. Thus, there is no single “best selection” and two criteria become important: the needs of the audience and the editor’s taste. As an example for the former, there is content that I personally love, but that is too obscure for a wider audience (such content includes posts of my own). In the end, no matter what choice we make, we can’t always make everyone happy. Some people want more introductory content, other people want more advanced content. Some want less jQuery, others want more. Etc. That being said, JavaScript Weekly’s publisher in chief, Peter Cooper has ideas for at least partially squaring this circle, so stay tuned.

References

1. The problem with blogs
2. GitHub: serve files to the web, with a single branch