Write a project introduction blog
Edit on github
Writing blog posts about your new project could help attract more visitors to your repo or website, educate prospective users and attract potential contributors. In this article, we recommend a list of topics that you might want to include in your Introduction Blog Post.
Our standard blog post includes 3 parts: First Impression, Main Content and More Information. It is up to you to decide which writing style you want to use. Whether it is personal, neutral or profession, please avoid to use terminologies that only you and your colleagues would understand. Screenshots, images are great, include them!
Part 1: First Impression <> Grab reader’s attention
-
Blog Title: When you write a title, you might want to think of ‘Google search’. What keywords readers likely to use when they search for particular information. Reports shows that How-to articles generate very good hits. E.g. How to … with [Project Name]
-
Subhead/Tag line: a catchphrase or slogan, could be something funny that triggers reader’s curiosity.
-
Short overview: explain what is your project about and the reasons why you want to share this project to readers. (3 - 4 sentences)
Part 2: Main Content <> Educate and convince readers
- Description: First, you could start with the story of how the project was made. People are often intrigued by origin stories and how things are made e.g. where did the idea for this new project come from? Who were the people behind it coming to realization? What’s the actual development process that puts all of the pieces together to create the final project.
Then, describe some cool features of the project. Tie those features with the benefits that they provide ideal customers.
-
How you or your company use [Project Name]: Put together a list of different problems that the project solves for you or your company. This will help readers understand how/when/where it can be used.
-
User scenario: Describe scenarios for ideal customers to use this project. Something that people can relate to e.g. tell a story about something that’s happening, how the project comes into play and saves the issue.
Part 3: Additional Information <> Provide readers action items
- Categories: specify which category(ies) your project belongs to.
- Language: list all the programming languages used in this project.
- Source: Repo link, project website, installation guide or documentation links.
A good example how Google features open source projects
