How to run a company tech blog, from pitch to publication

​

Overview

A tech blog is a technical publication through which a company shares knowledge about its engineering with people outside the company. Each article is written under an individual’s name, but readers take it as the company’s view. This page covers both the people who run a tech blog as an organization and the people who write the articles. It first defines the operating structure and the writing workflow, then covers choosing themes, managing expression and information risk, writing the article, and publishing and promoting it, and closes with how Findy runs its tech blog in practice.

​

Where a tech blog fits

Among the forms of external communication, a tech blog takes the role of explaining decisions and their reasons at length and leaving them in a form that can be read later. Unlike a talk or an event, an article keeps being found through search for a long time, so a single article remains as evidence of the organization’s technical standard. What distinguishes it from a personal blog is where responsibility lies. Metaphors, strong assertions, and comparisons with other companies’ products that are acceptable on a personal blog are read as the company’s position on an official publication. Running a tech blog therefore needs a way for the organization to confirm that content can be published, not only a way for writers to write what they want. At the same time, if the confirmation process is too heavy, writers drop away and publishing stops. The goal of running a tech blog is to keep writers able to write continuously while maintaining the quality and safety of the articles.

​

How the blog is run

​

Divide the roles

Running a tech blog involves at least three roles. Assigning the editorial team as a team and treating approval from any one member as sufficient keeps reviews from concentrating on specific people.

​

Define the writing workflow

An article is checked twice: before writing starts and after it is finished. Finding a mismatch in direction after writing has begun leads to a large rewrite.

​

Review the pitch before writing and the quality after writing

The check before writing is called the pitch review, and the check after writing is called the quality review. They check different things. The pitch review decides whether the article is worth writing; the quality review decides whether it is ready to publish. The pitch review checks that every one of the following criteria is met. The quality review checks the article against the structure, notation, and self-review points described in “Write the article.”

​

Choose a theme

​

Recommended themes

Themes based on the company’s concrete experience suit a tech blog. Because themes affect the company’s branding, even a recommended theme may not be publishable. Themes not on the list can be discussed in the review of the overall plan.

​

Themes to avoid

The following themes carry too much risk for an official company publication and should be avoided.

​

Manage expression and information risk

​

Ethics of expression

The standard for judging expression risk is not the writer’s intent but how readers could receive it. If an article causes a backlash, “that was not my intent” does not hold. On an official company publication, avoid the following expressions.

• Comparing people to animals, objects, or machines (dehumanization). Comparing people to animals has historically been used to justify discrimination.
• Applying workplace and HR vocabulary such as “assigned,” “manage,” or “report” to animals or fictional beings.
• Thought experiments using extreme settings such as animals, aliens, or robots. Even if the body says “this is a metaphor,” the title or a heading alone gets clipped and spread.

Before publishing, check for possible misreadings with the following four tests.

​

Sensitive information

Screenshots and photos capture unintended information. In screenshots of internal chat or documents, blur icons, names, timestamps, and project names. Light blurring can remain legible, so cover them fully. In desk photos, also check screens visible on monitors and notes on the desk. Source code can reveal internal structure or vulnerabilities through variable names and numbers. When including sample code, replace company-specific variable, function, and class names with generic ones, and do not include API keys, tokens, internal URLs, or IP addresses.

​

Write the article

​

Structure

Readers expect a different structure depending on the type of article. For experience or reflection articles and detailed tutorials, no fixed structure is defined; only the approximate length is given. Prioritize a clear claim with evidence over length. Still, an extremely short article gives an impression of thin content, and an overly long one makes readers drop off. If an article grows long, consider splitting it into a series. Use headings starting from h2, and phrase them by their content rather than “first” or “second.” A good target is that reading only the h2 headings conveys the whole article. Place a table of contents right after the self-introduction, before the body begins.

​

Title

The title affects whether an article is read as much as its content does. Make the title convey the conclusion, and put a concrete keyword such as a tool or technology name at the beginning. Avoid patterns that AI tends to generate, such as “3 lessons from…,” “How failure turned into growth…,” “The complete guide to…,” “…explained thoroughly,” “The road to…,” and “The secret of….” Short titles are memorable, but conveying the content takes priority.

​

Introduction and summary

In the introduction, make the following clear at the start so readers can judge whether the article is relevant to them.

• Which tool, technology, or event the article is about
• The intended reader and what they will learn
• The background or motivation for writing

In the summary, write the conclusion you most wanted to convey, the knowledge or actions readers can take away, and the outlook. Opening with “How was it?” or closing only with “I hope this is helpful” leaves no conclusion with the reader.

​

Showing numbers and evidence

When claiming an improvement, show before and after as numbers. Write “reduced from 2 hours to 5 minutes” rather than “processing became faster,” and a verifiable value such as “maintained above 90%” rather than “nearly 100% coverage.” Accompany numbers with the measurement environment (production, staging, or local), the sample size or period, and the baseline for comparison. When quoting external information, add numbered references in the text and list links to official documentation and event pages as references at the end of the article.

​

Tone and notation

Keep the tone neither too stiff nor too casual. Prefer expressions that lead forward, such as “in addition to …, … is increasingly required,” over openings rooted in anxiety, such as ”… is becoming hard to get value from.” When writing about a problem, first mention the strengths of the tool or method. Keep notation consistent within the article.

• Write product and technology names in their official form (GitHub, JavaScript, Cloud Run).
• Do not put spaces between English words and Japanese text.
• In Japanese, use 「次の」 rather than 「以下」 to introduce what follows.
• Limit bold to one or two places per heading, and keep italics, underlines, color, and horizontal rules to a minimum.
• Do not break lines after every sentence within a paragraph; separate paragraphs with blank lines.

Heavy use of bullet points, lists always aligned to three items, and mechanical lists in the form “Item: description” tend to make text look AI-generated. Write content that needs explanation as prose.

​

Self-review

Before requesting review, reread the article three times from different perspectives. A single read leaves oversights. Also check that the table of contents and the link to the careers page are present, that no placeholder text such as “TODO” remains, and that no links are broken, and confirm the appearance in the preview.

​

Publishing and promotion

​

Before publishing

Before publishing, confirm that all review comments are resolved, that you have revisited the title, that post-reading navigation (links to the careers page and related articles) is in place, and that the featured image is set. Creating featured images from a shared design gives the blog a consistent look. If you change the title, recreate the image as well.

​

Timing

Use your blog’s analytics to identify the days and times when articles are read, and schedule the publication accordingly. At the moment of publication, also announce the article from the official social media account.

​

Promotion and analysis

After publishing, the writer shares the article in internal channels and on their own social media, and asks colleagues to spread it as well. Colleagues reading and reacting to the article becomes the trigger for it to reach outside the company. Check readership with an analytics tool and a search performance tool. Because the effect of external communication is hard to attribute to individual articles, evaluate the activity as a whole over a sufficient period rather than evaluating writers by the numbers of each article.

​

Correcting a published article

When an error is found after publishing, correct the article. Before correcting it, pull the latest state from the blog service. If you edit while the content edited directly in the blog service differs from your local copy, those updates are lost.

​

How Findy runs its tech blog

Findy publishes its tech blog on Hatena Blog and manages article manuscripts in a GitHub repository. Reviewing articles through pull requests, the same way as code, lets engineers write and review in the same flow as their everyday development. To sync Hatena Blog with the GitHub repository, Findy uses Hatena-Blog-Workflows-Boilerplate, published by Hatena. The GitHub Actions workflows for pulling and syncing drafts and reflecting published articles are based on this boilerplate.

​

From writing to publication

​

What the quality review command does

The quality review command runs the following steps in order, based on the writing guidelines. The guideline file in the repository is the single source of truth, referenced both by the Claude Code commands and by reviews using GitHub Copilot Chat in Agent mode. Whichever tool a writer uses, they are reviewed against the same standard.

​

Operating rules

​

Related pages