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.

layout: post
title: Author information in jekyll blog
categories: [ruby]
author_github: neerajdotname

is powered by
In every blog we display author's name,
author's twitter handle,
author's github id
author's avatar.
In this blog
I'm going to discuss
how we collect all that information
in a simple manner.

We create a directory called ___data__
in the root folder.
This directory has a single file called __authors.yml__
which in our case looks like this.

We do not need
to do anything to load __authors.yml__ .
It is automatically loaded
by jekyll.

When we create a blog
then the top of the blog looks like this.

Notice the last line
where we have put in the author's github id.
That's the identifier we use
to pull in author's information.

In order to display author's name
we have following code
in the layout.

Similary to display author's twitter handle
github id
we have following code.

Now the blog will display the author information
all this information
is nicely centralized
in 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.