How to Write an Article for Semaphore Blog

Semaphore is excited about building a collection of technical articles that help everyone become a well-rounded software developer.

Our goal is to cover both cutting-edge technology and timeless topics on building products and collaborating within an engineering team.

For this reason, the Semaphore blog is open for contributions and the goal of this article is to provide some style guidelines for writing new tutorials.

About the audience

Depending on the subject, Semaphore’s audience are people with one of the following titles:

1. Software developer
2. Software architect
3. DevOps engineer
4. Tech lead or executive (Director of Engineering, CTO)

After reading, they should have either:

• Thoroughly learned about a new topic or how to use a tool, e.g. what is continuous integration.
• Done something from start to finish, e.g. packaged a Node.js app with Docker and set up CI/CD using Semaphore to Kubernetes.

How to write readable content

The reader could be doing a million other things right now, but somehow they’ve chosen to read your article. So make it easy for them by optimizing for clarity:

• Have a number in the title if possible.
• Write in a way that any smart person will understand.
• Never go for more than 3 paragraphs without one of the following:
  • Code snippet
  • Picture
  • Heading
  • List
  • Diagram
  • Chart
• Always use active voice.
• Always cite your sources to outside information.
  • For example, if you say that a Deno HTTP server can handle 25k requests per second, you need to provide a link to it.
• Never use commas to separate ideas, thoughts, principles, components.
• Always use lists to separate:
  • Ideas
  • Thoughts
  • Principles
  • Components
• If your lists contain multiple words, bold the first word:
  • Ideas: are fragile
  • Thoughts: have wings
  • Principles: are very important
  • Components: make up the system
• Don’t avoid active voice.
• Prefer shorter sentences and paragraphs. Use hemingwayapp.com to edit them.
• Use grammarly.com to catch basic mistakes.

Article length

We recommend:

• 1,000 – 1,500 words for tutorials with code
• 1,500 – 2,000 words for articles

Person and tone

Semaphore articles should educate the reader, which makes writing them different from personal blogging:

• 🚫 Avoid personal opinions, experiences and feelings.
• 🚫 Avoid unnecessary adjectives, comments and out-of-place humor.
  • For example, instead of “Thanks to the awesome XY community, there are many plugins”, you could write “The XY community has created many plugins”.
• ✅ Write in a friendly, but formal tone.
• ✅ Use analogies or metaphors that help understand a process the subject at hand.

Write in the first person plural (we, our) and second person (you, your). Here’s an example:

Our first test will check if the homepage really displays “Hello World” message. Since we’re testing by opening a real browser, the test needs some setup and teardown. […] You now have the basic setup for testing web applications with Selenium.

How to write tutorials

Tutorials are a type of an article which includes code snippets and steps to reproduce a solution.

Semaphore tutorials should be as focused and self-contained as possible. Your objective is to guide the reader to a solution to their problem:

• ✅ Always specify all prerequisites for completing the tutorial.
• ✅ Spell out every step you are taking as clearly as possible.
• ✅ Explain in detail any new concepts that you introduce in the code or text.
• ✅ Link to an existing Semaphore article for a full introduction to a topic whenever possible.
• ✅ Always mention the file where the code snippet belongs:
  • in the text, and/or
  • in a comment as the first line of the snippet.
• ✅ Link to an existing Semaphore article for a full introduction to a topic whenever possible.Strike a balance between the complexity of the tool/idea and the code examples.
  • For example, our Kubernetes tutorials work with a simple microservice that talks to a database, not Nginx Docker image.
• 🚫 Do not ask the reader to go to an external site in order to learn how to complete a simple task that you can easily explain in the article.
• 🚫 Avoid using foo, bar and similar generic names.
• 🚫 Never submit a draft before verifying all the steps taken in your tutorial yourself, in an environment you instructed the reader to set up.

Learn from real examples

Browse through the archives to get an idea of what your article should look like. When in doubt, ask your person of contact at Semaphore for feedback. Happy writing!