Skip to end of metadata
Go to start of metadata

Hi! Zak from Magnolia here. This post is about how I think we should write blog posts for the Talkoot project.

We are publishing the guidelines under the CC-BY license so that others can benefit from them. I also hope that I'll get feedback. Please give the post a read and leave your comments below. I'll use your input to improve the guidelines.

This post is now out-of-date. Our current blogging guidelines are at [Blogging guidelines].

Draft Talkoot blogging guidelines


We hope that our blogging will lead to people discussing and participating in the Talkoot project.

The first challenge is getting the attention of the Magnolia community - a group of busy people from different backgrounds. To get people's attention, I think that we need to:

I also want our blog posts to motivate people to participate in Talkoot. There are many ways we can do this. In blog posts, a simple way is to:

Finally, we should not try to make our blog posts (or these guidelines) perfect. Perfect is the enemy of good and of done.

More on each of these points below.

Make regular blog posts

I think that people want to get interesting information:

  • regularly (but not too often)
  • at predictable times
  • that are convenient for them.

We can be more regular by having posts ready before we need them. If anything interrupts us, we can use what we've already written.

If we have posts ready to publish, it is easy to be predictable: we just pick times to publish and stick to them.

Posting at convenient times is a challenge. We are writing for people in many time zones. No matter when we post, it'll be the middle of someone's night and they'll be late to the discussion. As a compromise, let's try posting on Tuesdays and Thursdays near the start of my day (15:00 UTC). We won't compete with anyone's Monday, and I can engage with people who comment on the post over the rest of my day. After that, the Magnolians in Europe can pick up where I left off.

Write short, well-structured posts in plain English

We are writing for busy people with different levels of fluency in English.

Fluent readers often skim text, looking for interesting parts.

Less fluent readers may read word-by-word, needing more time to find what matters to them.

Readers who use machine translation are best served by text that uses simple words, simple grammar and simple structure.

Busy people have less attention and need less content that is better structured.

Jakob Nielsen's guidelines on writing for the web address these needs and are worth reading.

I've listed some important guidelines below:

  • Important things first. Put the most important points at the beginning of the post, so that readers can quickly decide if the entire thing is worth reading.
  • Keep posts around a 1000 words or less. A careful read of 1000 words should take most readers less than 10 minutes, and fluent readers can skim this amount of text in a minute or so.
  • Use short sentences. Usually, short sentences are easier to understand than long sentences.
  • One point per paragraph. Keep paragraphs short and limited to a single key point.
  • Use common words. Most readers should not need to use dictionary to read our blog posts.

Make posts valuable to readers

Right now, we are writing for Magnolia community members who might participate in Talkoot.

Guessing at what they need, I think that we should have one post a week on something concrete (like a task that can be done) and one post a week on something abstract (like this post).

As people participate, we should find out what they need and adjust our style and focus to fit.

One major topic per blog post

We can make blog posts simpler by focusing on one major topic. This simplicity should lead to easier editing, simpler discussions around the blog post and so on.

Focusing on a single topic will also make blog posts easier to search for and update.

Remember the bigger story

Having short and simple posts means that we need to tell our story in parts.

Right now, there are a few big stories (or threads) that we want to focus on.

One thread is about the hows and whys of the Talkoot project. Posts should cover topics like:

  • Why we're running the Talkoot project
  • Why participate in Talkoot
  • How to get the most your participation

Another thread should focus on what is happening in the project. Posts should cover topics like:

  • How the project is progressing
  • What the roadmap looks like
  • What work needs to be done now

Ask for reader participation

If we want reader participation, we should ask for it.

Asking at the end is natural - if someone has read the entire post, they're likely interested and have something to offer.

Asking at the beginning lets readers know what we'd like from them.

Make it easy for readers to participate

We can make it easier for readers to participate if we ask for simple things that are well-described and easy to do. We also should make sure that we only ask for what we really need, instead of asking for others to do our work for us.

Make it beneficial for readers to participate

This topic needs a separate blog post to discuss how and why we want to make participation good for everyone involved.

We should say what we think the benefits of participating are. We should also ask readers how participating could benefit them.

Perfect is the enemy of good and done

Our blog posts should be good, but not perfect. The most important thing is to stimulate conversation and enable participation. If what we write leads to good discussion and good collaboration, we're doing the right thing.

Thanks for reading!

If you can, help me in the following ways:

  • Please comment on this post. Your input will help improve these guidelines, which will lead to better posts in the future. I'm most interested in your personal experiences, either as a reader or a writer. Also, I have a much easier time writing when I get feedback on my writing.
  • Follow Talkoot on Twitter so that you can more easily keep up-to-date with what the Talkoot team is working on.

Next week, I'll be writing about how we are designing the Talkoot project for collaboration.

Unable to render {include} The included page could not be found.
  • None
  1. Jun 01, 2012

    Thanks for kicking this off! My first comment is regarding the look & feel of the blog post. It looks like any wiki page we have. We should provide a better reading experience, at the very least I suggest to fix the width of the content so the contents are easier to read. But really, it would be nice if it doesn't look like the wiki pages.

    1. Jun 01, 2012

      Zak Greant AUTHOR

      Thanks for the input, Boris!

      I've adjusted the CSS for blog posts in this space, working to improve readability by shortening lines, increasing font sizes and increasing the space between lines.

      Here's a before screenshot and an after screenshot. Click each image to see full size.

      If we upgrade to a newer version of Confluence, we'll be able to take advantage of the significant improvements that Atlassian has made to the design of the wiki.

  2. Jun 15, 2012

    The question about best time to blog is interesting! There is some research into this.

    • People read blogs most in the morning, so publish early in the morning.
    • Retweet activity peaks Friday 4pm EST. This is be the best time to tweet a blog post for maximum retweet reach.
    • Posts published in the morning on Saturday and Sunday, around 9a.m. EST, are shared more on Facebook.

    So we can come up with a rule of thumb: "Post on Friday morning at 9 a.m., tweet at 4 p.m., and share on Facebook Saturday morning."

    Or if you are in Switzerland: "Post on Friday at 3 p.m., tweet at 10 p.m., and share on Facebook Saturday afternoon."

    However, the same research suggest that if you have a very popular blog and lots of posts, publishing multiple times per day leads to a huge increase in a blog's success. This tells us that rather than focusing one perfect day or time, we should aim to publish at many times, and on many days.

    1. Jun 15, 2012

      Zak Greant AUTHOR

      Hey Antti,

      Thanks for the input! Let's adjust the guidelines accordingly. (smile)

  3. Jun 18, 2012

    I just read Isa's post about going to Miami. At 618 words the post seemed long. I suggest cutting the max length recommendation by half to 500 words. Thoughts?

    1. Jun 18, 2012

      Zak Greant AUTHOR

      I'm game for that.

      Also, now that there's feedback that has this post diverging from what we're doing, I'll put the guidelines somewhere else and link to them from the top of the post.