How we work

Write blog using ventilated prose style

We write blog using ventilated prose style. For example, for the Author information in jekyll blog, we wrote it as given below. In the sample shown below, we have removed all code examples since we want to show how sentences are written and not code.

2layout: post
3title: Author information in jekyll blog
4categories: [ruby]
5author_github: neerajdotname
10is powered by
12In every blog we display author's name,
13author's twitter handle,
14author's github id
16author's avatar.
17In this blog
18I'm going to discuss
19how we collect all that information
20in a simple manner.
22We create a directory called ___data__
23in the root folder.
24This directory has a single file called __authors.yml__
25which in our case looks like this.
27We do not need
28to do anything to load __authors.yml__ .
29It is automatically loaded
30by jekyll.
32When we create a blog
33then the top of the blog looks like this.
35Notice the last line
36where we have put in the author's github id.
37That's the identifier we use
38to pull in author's information.
40In order to display author's name
41we have following code
42in the layout.
44Similary to display author's twitter handle
46github id
47we have following code.
49Now the blog will display the author information
51all this information
52is nicely centralized
53in one single file.

This style of writing is also called 'Semantic linefeed'. That article has lots of comments, and you can see even more discussion on hacker news.

Here are some simple rules we follow.

  • Put a link in its own line.

That line should have just the link and nothing else.

  • Always start a new stentence after line break.

  • Try to give and a line of its own.

The advantage is that anything can be added before and easily without changing the whole line.

We are less concerned about where to break the sentences. We care more about not having long sentences.

This style of writing has helped us keep sentences short and meaningful.