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:
- 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
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 .
- 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
- The problem with blogs
- GitHub: serve files to the web, with a single branch