This is the README for authors!
Please add your post to the
_drafts folder. This allows us to control when your post goes live, even though you’ve already checked it in.
At the top of each post, you’ll see some front matter. This is metadata for your post. It looks something like this:
layout: post title: “Scaling Query Suggestions in a COVID-19 World” description: How Yext is using Answers to help provide COVID-19 information and resources for New Jersey and the world, and how we built a system to handle a two order of magnitude spike in requests from a single press conference. author: sstern permalink: /post/scaling-query-suggest cover: /img/2020/state-answers.png —
Please ensure you have these six fields on your post!
After your front matter block, you want the first thing in your post to be a paragraph. Our current theme slightly largens the font of the first paragraph. Please don’t have a header as your first thing after your front matter—this screws up how the post cards (e.g. on the home page).
Additionally, please choose a cover image! This is an image that is displayed prominently at the top of your page, as well as in thumbnails. You can reuse an image in your post or pick something completely different. If possible, we’d recommend something visually interesting.
If you’re a new author, you’ll want to add an author page for yourself! Add an entry in
_data/authors.yml. There’s a sample at the top of the file that you can look at.
First, especially for newer authors, find a buddy to work with you on your post! You likely want someone who has shown that they can produce reasonable writing. Vincent’s always available if you don’t have anyone in mind, but there are plenty of engineers who write well at Yext! If helpful/applicable, you may also want to find someone who has technical expertise in your topic.
Once you’re happy with your draft, send it to Vincent for review. As the post shapes up, he’ll send it to Rob for final approval.
Once the post is good, go ahead and ship it! (Leave it in the
_drafts folder.) At publish time, Vincent will move the post and republish the site.
For the most part, you are free to write how you’d like! Style, tone, humor, etc.—all up to you. We do ask that you don’t write anything that would make us look really bad—lessons learned are okay, but we don’t want people to walk away with the wrong impression about the stability of our software!
Here are some tips, in no particular order:
- Use your normal voice (i.e. how you’d normally speak). It can help to think about how you’d say something if you were actually speaking to another person.
- Consider your audience! How familiar do you expect them to be with your topic? What context do you need to explain?
- Share an experience, and help the reader get a sense of what you got to experience! This applies regardless of whether or not you are writing about something technical (e.g. how switching from mercurial to git affected development) to something non-technical (e.g. our latest offsite).
- Photos and/or code snippets can help to visually break up what otherwise looks like a wall of text.
- Keep writing (and reading)! It feels awkward to write at first, but the more you do it the better you get.
- Writing takes time! It’s normal if it seems to take more time than you expect to write your post.
- Tell a story! This doesn’t (necessarily) mean to imagine a fictional universe. Rather, lay out some kind of narrative—we had problem X and constraints Y, we experimented by doing Z, and voila we now built/learned/gained XYZ.