A Guideline for Writing Research/Tech Blogs

Intro

In Almeta you have to write a lot for those research tickets you have in a Sprint. You’ve to read tons of research, academic, and sometimes boring paper. But, when you write your proposal, you don’t have to write like them. As a matter of fact we want to be as close to non-techies as possible when writing our tech blogs.

So, you’re an engineer and you love to code. You are a machine learning engineer and you love to read. You’re both and here comes a research/investigation ticket. You read, read, and read some more and now comes the time that you have to write a blog post. And you’re not liking it. It’s OK. It’s understandable. Here are some guidelines for you:

Basics

  • Strive to make your content self-contained and can be understood by reading your article only. But not repetitive. Always link other articles when tackling any idea that is not in your article’s main interest.
  • Let the people know what you’re talking about: Always start with an “Intro” section.
  • Let the people know what you think: Always end with a “Conclusion” section.
  • Always prefer shorter sentences. They are easier to read.
  • Don’t have more than 2-level deep subsections.
  • Multiple consecutive titles without any leading paragraphs in between are prohibited.
  • Always set the Category of the blog post.
  • Titles are always Camel-cased.
  • Always add tags to the article. They make them more SEO-friendly.

Style

  • Simplicity: Follow a joyful, but academic style writing. These blogs are for the public techies to read as well as non-techies. An engineer should be able to understand and enjoy any piece you write. We’re in a fight with everything complex or an overkill. Our writing style should be clear, clean, and easy to understand and academic. In that order.
  • We’re visual creatures: Draw a Mind Map of what your are talking about. Make it digestable by a newbie, by a beginner’s mind. We’re not only targetting high techie people. If we can be a help for newcommers to ML/AI, as well as ML/AI beasts, then we are truly helping everybody.
  • Fonts, italics, bolds: Just use 1 big font for headlines, another big font for subsections and normal default for the rest. Don’t use italic bold for a subsection. Be consistent and clean.

Clean, Clear, Research Machine

  • Content is the king. And style based on fads means nothing. You are responsible to be a great mathmetician. You’re an engineer and you’re obsessed about details. Act accordingly.
  • Always mention N, the sample size, when mentioning any percentages (e.g. “where 7% of the customers (where N = 69)”)
  • Always mention your source (reference) but don’t shy to steal like an artist for non tech stuff.
  • Matrix was a good movie: Always try to use matrices instead of bullet points with heavy text when listing: technologies, datasets, plans, etc. Matrices consume less space, they make your idea clearer and most importantly, they allow direct and simple comparison between entities which is the vital point when listing any similar entities.
  • Say clearly what’s your opinion: Always put your recommendation/opinion at the end when presenting ideas. Clearly show that it’s YOUR opinion or Almeta’s choice or recommendation.
  • Always mention what is your proposal and what are we planning to do.

Corrections

When a QA-er will review your research ticket, he’ll add his comments in wordpress as XX. Sth like: “XX: bla bla bla.” You can search then for the XX and read the edits. We found that this is a good start to add comments in wordpress. Not the nicest, but it works.

That’s it. Happy writing!

Leave a Reply

Your email address will not be published. Required fields are marked *