> ## Documentation Index > Fetch the complete documentation index at: https://lib.findy.co.jp/llms.txt > Use this file to discover all available pages before exploring further. # How to run a company tech blog, from pitch to publication > How to publish externally through a company tech blog: the editorial roles and workflow, the pitch review before writing and the quality review after writing, choosing themes and managing expression risk, writing the article, and publishing and promoting it. ## 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. | Role | Responsibilities | | - | - | | Writer | Plans the article, writes it, and completes a self-review before requesting review | | Manager | Reviews the article from a position that knows the writer's work | | Editorial team | Confirms that the article's direction is consistent with the blog as a whole and that the expression carries no risk | 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. **1. Register the plan** Register the article plan in your task management tool and set the due dates for the first draft and the review, and the planned publication date. Setting dates up front lets reviewers reserve time. **2. Get the overall plan reviewed** Summarize a working title, an outline of what you intend to write (bullet points are fine), and the conclusion, and ask your manager and the editorial team to review it. At this stage the review checks whether the theme is suitable for the tech blog and whether the conclusion is clear, not the quality of the prose. **3. Evaluate the value of the pitch** Before writing begins, evaluate whether the plan contains knowledge that is new to readers. The criteria are described in the next section. **4. Write the draft and self-review it** Write the draft following the writing guidelines and checklist, and check its quality yourself before requesting review. **5. Get the article reviewed** Ask your manager and the editorial team to review the draft, address their comments, and obtain approval. **6. Schedule and publish** After confirming the title, the post-reading navigation, and the featured image, schedule the publication date and time. **7. Promote the published article** Share the article in internal channels and on personal social media so it reaches more readers. ### 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. | Criterion | What to check | Example that does not pass | | - | - | - | | Non-obviousness | The claim is not already known to experienced readers | Ends with a truism such as "testing matters" | | Originality | At least two elements available only from this article, such as numbers, details of a failure, procedures, or before/after comparisons | A rehash of official documentation or existing articles | | Actionability | At least one thing readers can change the next day | Ends with "keep this in mind" | | Target reader | The role and experience level (junior, mid-level, senior) are clear | It is impossible to tell who the article is for | | So what? | You can answer "so what?" by saying whose what changes | "AI is convenient" | The quality review checks the article against the structure, notation, and self-review points described in "Write the article." > [!TIP] > > For both the pitch review and the quality review, leave the result as a comment on the plan's issue or the article's pull request. Reviewers then do not need to recheck the criteria that were already evaluated and can spend their time on the rest. ## Choose a theme ### Recommended themes Themes based on the company's concrete experience suit a tech blog. | Theme | What to watch for when writing | | - | - | | Sharing technical knowledge | Avoid content that is too simple, such as just trying a tutorial | | Case studies, successes and failures, and retrospectives | Include the background and the reasons for decisions | | Experience with development processes, agile, and team building | Write about what happened in your team, not general theory | | Contributions to open source as an organization | Show the content and background of the contribution concretely | | Hiring, introducing the organization, and collaboration between teams | Add concrete examples that convey how the organization actually works | | Industry and technology trends, information from abroad | Confirm the facts and cite sources | | Reports on technical events and seminars | Write about the content that stood out and what you learned | | Joining stories and engineering career paths | Center on the company and organization rather than personal impressions | 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. | Theme | Why to avoid it | | - | - | | Comparisons of tools or products | The company does business with vendors, and raising one lowers another | | Criticism, negation, or fault-finding | Taken as the opinion of the company as a whole | | Criticizing or naming competitors | Affects relationships between companies | | Confidential information, personal information, or other companies' information | Even already-public information requires checking whether republishing it is appropriate | | The company's future strategy or the KPIs it tracks | Lets outsiders infer business decisions. Acceptable when close to general knowledge | | Content that violates the law | Copyright infringement, unauthorized access, scraping that violates terms of service | | Unverified information | When quoting, link to the source | | Overly casual content | A strong element of joking is inappropriate for a company publication | ## 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. | Test | What to check | | - | - | | Title-only test | How someone who sees only the title, without reading the body, would interpret it | | Clipping test | How a part of the article would look without context if spread on social media | | Most-hurt-person test | Who could be hurt by this article, and how they would feel from their position | | International test | How readers abroad, especially in English-speaking regions, would take the expression | ### 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. > [!WARNING] > > Writers themselves confirm that images and screenshots are safe to share before adding them, without waiting for review. ## Write the article ### Structure Readers expect a different structure depending on the type of article. | Article type | Recommended structure | Approximate length | | - | - | - | | Technical explanation | Background and problem → options considered → implementation details → results (before/after) → outlook → summary | 3,000–5,000 Japanese characters | | Event report | Event overview → content → what you learned → who it is recommended for | 2,000–3,000 Japanese characters | | Experience or reflection | — | 2,000–3,500 Japanese characters | | Detailed tutorial | — | 5,000–8,000 Japanese characters | 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. | Perspective | What to check | | - | - | | Writer | Can you state the main message in one sentence? Is there evidence for it? Do the title and conclusion match? | | Reader | Is it understandable without prior knowledge? Does it answer "why?" and "specifically?" Is there something to take away? | | Critic | Does it anticipate counterarguments and exceptions? Is there anything that could read as criticism of others, boasting, or condescension? Could a personal opinion be mistaken for the company's official view? | 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](https://github.com/hatena/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 **1. Manage the plan in GitHub Projects** Create a task in the tech blog's GitHub Projects board and open an issue from the article template. In the issue, fill in a working title, the summary and conclusion, and the due dates for the first draft, the review, and the planned publication, and set the status to "Todo." **2. Get the plan reviewed in the issue** Mention your direct manager and the editorial team's GitHub team as reviewers. The editorial team is assigned as a team, and approval from any one member is sufficient. **3. Evaluate the pitch with Claude Code** A Claude Code command for pitch review evaluates the plan against five criteria: non-obviousness, originality, actionability, target reader, and so what. It can evaluate the content of the issue, or collect the plan interactively before evaluating. Writing starts only after a PASS, and the result is posted as a comment on the issue. **4. Create a draft on Hatena Blog and sync it to GitHub** In the Hatena Blog editor, save a draft with a unique title such as `username-date`. Running the GitHub Actions workflow that pulls drafts with that title automatically creates a pull request containing the draft. **5. Edit the article on the pull request** Pushes to the draft pull request are synced to the Hatena Blog draft through GitHub Actions, so you can check the rendering in the preview. Images added to the repository's year/month directories and referenced from the article are uploaded to Hatena Blog. **6. Review quality with Claude Code** A Claude Code command for quality review reviews the article. Repeat fixing and re-reviewing until the score reaches 90 or higher, then post the result as a comment on the pull request. **7. Get reviewed by your manager and the editorial team** Assign your manager and the editorial team as reviewers on the pull request and obtain approval. **8. Publish with a scheduled post** Merge the pull request while keeping the `Draft: true` line that marks it as a draft, then set the publication date and time in the Hatena Blog editor to schedule the post. At the same time, enable posting to X on publication so the official account announces it. **9. Share it inside and outside the company** After publishing, share the article in company-wide and engineering Slack channels and in your own times channel, and ask colleagues to spread it on social media. ### What the quality review command does The quality review command runs the following steps in order, based on the writing guidelines. | Step | Content | | - | - | | Risk check | Detects backlash risk, sensitive information, comparison or criticism, and unsupported assertions. If there is a problem, fix it and run again | | Lint check | Mechanically detects typos, inconsistent notation, spacing, and Markdown syntax | | Self Review | Checks the article against the checklist and the three perspectives and scores it out of 100 | | Fix Plan | Below 90, presents concrete rewrites | | Consistency with the plan and overall check | Confirms that the article matches the plan in the issue and that the article flows consistently as a whole | | Comment on the pull request | At 90 or above, posts the review result to the pull request after confirmation | 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 > **Publication timing** > > To maximize reach, articles are published on Monday or Friday (the next business day if it is a holiday) between 7:00 and 10:00. Scheduled posts are set for 7:00. > **End of the article** > > Every article ends with a link to the careers page along with a standard sentence. > **Product names** > > Product and company names are written in their official form, such as Findy, ファインディ株式会社, Findy Team+, Findy Tools, Findy Freelance, and Findy Conference. Forms such as "FINDY" or "株式会社ファインディ" are not used. > **Featured image** > > For a consistent look, featured images use a designated color scheme from a shared design template. > **Preparation for first-time writers** > > Create a Hatena ID, tell an administrator, and be added as a member of the Hatena Blog. Set your name and icon in your Hatena profile so readers know who wrote the article. ## Related pages > **[The role of DevRel](/devrel/engineering-culture.md)** > > The role that external communication, including the tech blog, plays for an organization. > **[Engineer Growth](/organization/engineer-growth.md)** > > Read this when placing article writing within growth through learning and sharing. > **[Onboarding](/organization/onboarding.md)** > > How to support new members, who often write a joining story, until they work autonomously in the organization. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.